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TOOLS OF 
THE TRADE 


by Tim Monroe 


Code Warrior 6 


A Look at tbe Latest Mac 
Version of Metrowerk's 
Development Environment 


Introduction 

CodeWarrior 6.0 (C\V6) is the 
latest version of Metrowerk’s popular 
integrated development environment 
(IDE) for Macintosh and Windows 
(and, I believe, the first version to 
carry the Motorola brand name). In 
addition to all the standard 
improvements you'd expect to find in 
a major release of a professional IDE 
(bug fixes, greater conipliance with 
exi.siing standards, improved 
performance, and the like), 
CodeWarrif)r 6.0 takes one major .step 
forward: all important parts of the 
software development environment 
have been Carbcmized, including the 
IDE itseif, PowerPiant (the object- 
oriented application framework), 
Constructor, and Profiler. This means 
that it’s possible to do complete 
application development on “classic” 
Macintosh operating systems (Mac OS 
8,x and 9.x) and on Mac OS X, 
(CodeWarrior 6.0 also runs on 
Windows computers, but 1 did not 
receive a review copy of the Windows 
install disk, so 1 canT comment on 
how well that new version works.) 


Some Test Drives 

I first took CodeWarrior 6.0 for a spin on Mac OS 
9.0,4. As usual, installation was a snap. The IDE wanted to 
convert my existing project I'ile.s for use with the new IDE 
(version 4.1, for what it's wortli). After that, compiling, 
linking, and debugging proceeded exactly as they did 
under previous versions of the IDE. The entire 
CodeWarricir 6.0 suite has received a minor facelift; for 
in,stance, the Finder icons are different, and the project 
window (shown in Figure 1) has undergone some 
reorgani?:ation. (In earlier IDEs, the tabs hung down from 
the top of the window,) 
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figure L A project window under Mac OS 9- 


Tim Monroe is a software engineer on Apple’s QuickTime engineering team, You can contact him at monroe@apple.com, Hi.s 
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Then I decided to get brave. I usually like to develop 
Windows versions of my applications using the Mac IDE. 
T didn't have the Windows IDE, but the Mac installation 
still includes compilers and linkers for x86 development. 
Once again, my existing Windows projects compiled and 
linked flawlessly (after allowing the IDE to make the 
necessary project conversion), CodeWarrior 6.0, however, 
uses a different method for specifying the remote target 
for two-machine debugging. Under previous versions, 
you could specify only a single remote target for all 
projects, in the IDE Preferences window (Figure 2). 



Figure 2. Setting a remote debugging target (CW 5). 


Under CW6, you can define any number of remote targets 
in the IDE Preferences window (Figure 3). Each 
individual project can then specify which one of those 
targets to use for any particular debugging session (see 
Figure 4). This is a very nice enhancement. 



Figure 3. Setting remote debugging targets (CW 6). 



Figure 4. Specifying a remote target. 


Pedal to the Metal 

Finally, I decided to get really brave and run the IDE 
under Mac OS X. I installed the Public Beta version of OS 
X on an external hard drive, booted up, and then 
launched the IDE. I must admit to having had a certain 
trepidation as the IDE launched, but my fears subsided as 
the project window opened and greeted me with its 
jaunty Aqua appearance (Figure 5). 
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figure 5. A project window under Mac OS X. 


Once again, the project compiled, linked, and ran 
flawlessly. Moreover, remote debugging between the Mac 
OS X machine and a machine running Mac OS 8.6 worked 
just fine. What did not work at all w^as local debugging — 
that is, trying to step tlirough the code on the Mac OS X 
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machine itself, (I kept getting a network timeout error; go 
figure!) After trolling the comp.sys.macprogrammercodewarrior 
news group, 1 discovered that 1 needed to perform the 
Codewarrior installation while running Mac OS X. Once I 
did that, local and remote debugging worked as expected, 
CodeWarrior 6 running on Mac OS X seems to be a 
fairly solid and stable product, at least in my preliminary 
tests. As is to be expected, there are some cosmetic 
glitches. Figure 6, for instance, shows a dialog box in 
which some of the text is clipped. All in ail, however, I 
was pleasantly surprised at how well the product 
performed, especially considering that it's running on a 
beta version of a brand new^ operating system. 
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Figure 6, A dialog box with dipped text. 


Conclusion 

Should you upgrade to CodeWarrior 6,0 from an 
earlier version? For most Mac programmers, this is a no- 
brainer; sure, stay up to date with the latest and greatest 
cools. This is especially true if you want to get your 
product working under Mac OS X or you want to do your 
software development under Mac OS X. You can develop 
Carbonized applications using CW5, but not under Mac OS 
X. For the complete Carbon story, and especially for local 
debugging under OS X, CodeWarrior 6,0 is the way to go. 

Some developers, however, might want to hold off 
making the leap to CW6, even though it's a fairly tiny leap 
in terms of code changes. If you're deep into a project 
that uses CW5 or earlier, you may want to finish that 
project before moving forw^ard. After all, since the 
compilers have become more compliant to the ANSI 
standards, some of your existing code might get signaled 
as non-compliant (especially if it is non-compliant). In my 
own projects, I didn't encounter any such problems, but 
of course your mileage may vary. In my mind, the abiiky 
to specify remote debugging targets on a per-project basis 
is worth the price of upgrading all by itself. MI 
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SOFTWARE 

EMGIMEERiniG 


By Paul E. Seving, Switzerland 


Patterns 


Introduction 

Meuse is a key objective of 
software engineering. A welbknown 
form of reuse is code (le., 
implementation) reuse^ as promoted 
by a procedure library for instance. A 
domain-specific framework also 
promotes implementatitjn reuse^ and 
in addition the reuse of analysis 
(namely of the domain) and design 
(tlrat led lo the architecture of the 
framework), Capturing and passing on 
analysis and design experience 
without the need for code can be 
achieved by the use of patterns. 

In this article, we give definitions 
of pattern, analysis pattern, design 
pattern, and architectural pattern, fin a 
future article on frameworks, we will 
also discuss the relationship between 
patterns and frameworks.) We do not, 
however, recap the histoiy of patterns 
(see, for instance, Appleton [3]). 
Nevertheless, note that software- 
development patterns were inspired 
by Christopher Alexander who, in the 
1970s, developed a pattern language 
for architecture [2] — the “house¬ 
building" discipline, that is, ncjt 
software or computer architecture! 

Patitrn 

Patterns are schematic, proven 
solutions to recurring problems. 
Basically, patterns are characterized 
by at least a name, a problem 


description, and a problem solution [15]^ A well-known 
name allows us to concisely refer to a specific pattern. It 
is certainly easier to refer to “the Adapter pattern" (see the 
example belcjw) than “the pattern that consists of entities 
which...". The problem description tells us in what 
situations the respective pattern is applicable. It includes 
conditions that must be met before applying the pattern. 
The problem solution explains how we can solve the 
problem. Tt typically does so as abstractly as makes sense 
for the particular kind of pattern. 

“Schematic" refers to the fact that, especially in 
patterns books, patterns are usually discussed according to 
some template. (For the sake of brevity, we will not do 
that in this article.) Different authors use different 
templates [e.g,, 6, 11]. “Recurring” refers to the fact that a 
probiem/solurion pair must be observed at least three 
times to be accepted as a pattern. 

Let us look at a simple example, the Adapter pattern. 
Assume that, in a certain context, we defined the interface 
of encrypiion/decrypiion Java classes to be as shown in 
Listing 1. 


Listing 1 


public interface Cipher 
( 

void encrypt( int[] plainText, iiit[] cipherText ): 
void decryptC intj] cipherText, int[] plainText ): 


Now we would like to have a Cipher instance that 
performs TDEA-encryption and —decryption [14]. For that, 
we need a concrete class that implements the Cipher 
interface. We could, of course, develop such a class from 
scratch. However, a good soul already did most of the 
hard work by developing a class that realizes IDEA and 
even made its source code freely available (see Listing 2). 
We are going to reuse this class. 


Paul E. Sevinv currently works as a software engineer for Switzerland-based Teamup AG. From January 2001 on, he will work 
for Trilogy Software, Inc. m Austin (Texas) and Paris (France). You can reach him at paul.sevinc@ubilab.org. 
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Listing 2 

public class IDEA 

f 

// fields 


public IDEA( lnt[] secretKey ) 
1 


// sec listing 3 


public void encrypt( inti] plainText» int[] cipherText ) 
[ 

super.cipher( true. plainText. cipherText ); 

I 

public void decrypt( int[] cipherText, int[] plainText ) 
[ 

super,cipher! false, cipherText, plainText ): 

1 


public void cipher! boolean flag, int[] source, int[) drain ] 
1 


// private methods 

] 


One problem remains, tliough: the type IDEA is not a 
subtype of Cipher^ l^ut Java is strongly typed. And even 
if Java was not strongly typed, we would still have a 
problem since the interfaces did not match in tlie first 
piace. — Enter tlie Adapter pattern* Instead of forgetting 
about the IDEA class altogether or of copying and 
modifying its source code (a highly error-prone 
approach), the Adapter pattern suggests to develop a 
class, a subtype of Cipher, that simply foi'^^ards requests 
to IDEA (see Listing 3). 


Listing 3 

public final class IDEACipher implement3 Cipher 
[ 

private final static int JteyLength = 16; 
private final IDEA adaptee: 

public IDEACipher! int[] key ) throws InvalidKeyException 
f 

if ( key,length i= keyLength ) [ 

throw new IuvalidKeyExceptlon( ); 


for ( int 1 ” 0: 1 < keyLength; ++i ) I 
if [ key[ 1 ] ^ D I| key[ i ] > 255 ) [ 
throw new InvalidKeyException! ); 

] 

] 


adaptee = new IDEA! key }r 


public void encrypt! int[l plainText, intfj cipherText ) 
[ 

adaptee.cipher( true. plainText, cipherText ): 


CHenl 

- ” -> 



fldeptee^ 

Adaptee 



fieqtfissTf^ 





Aitaptizr 


request 0 - 



adaptee ,spedfieRequestQ 


figure /. Object Adapter (adapted from [11]), 

The Adapter variant of Listing 3 is called the Object 
Adapter (it connects objects at run time through a 
reference, see Figure 1). Tlie Adapter variant of listing 4 
is called the Class Adapter (it connects classes at compile 
lime tliroLigh inheritance, see Figure 2), In Java, we clearly 
prefer the OI:)ject Adapter over the Class Adapter. But in 
C++, where IDEACipher could have inherited privately 
from IDEA (and thus not be of type IDEA), the Class 
Adapter is a viable akernarive. 



Figure 2, Class Adapter (adapted from [llD- 


public void decrypt! int[] cipherText, int[] plainText ] 
i 

adaptee*cipher! false» cipherText, plainText J: 


Note that, since IDEA was developed first, we could 
also have defined IDEACipher as shown in Listing 4, 

Dsting 4 

public final clans IDEACipher extends IDEA implements Cipher 
f 


In shoiT; Name: Adapter (also know as Wrapper) 
Pn>hlem Descnption: Class (Adaptee) whose implementation 
cannot lie reused (by Client) because its tyj^e or at least its 
interface does not meet certain requirements. 
Frfjblem Solution: Develop a class (Adapter) whose type or 
interface does meet above-mentioned requirements and whose 
miplementation mainly consists of forwarding requests to (and 
remrning replies from) Adaptee in a suitable form. 
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Architecture and Design 

According to Stroustrup [23J, software development is 
an iterative and incremental process basically consisting of 
analysis, design, and implementation, where the software 
design steps result in the softw'are architecture. This view 
of architecture being the result of design is not 
uncommon. And we adopted it in the first paragraph of 
the introduction, when we said that franiew^ork design 
leads to the framework architecture. 

However, the software-engineering community in 
general and the patterns community in particular denote 
by architecture another software-development step 
(analysis, architecture, design, implementation). We 
adopted the latter view in die last paragraph of the 
introduction, when we considered architecture to be a 
discipline, and for the remainder of this article. 

So what is architecture? Just as is the case for 
components [22, CS99], the software-engineering 

community is stiuggHng with a definition for architecture 
[4, 7]. Very, very loosely speaking, architecture is coarse¬ 
grained design (higher level), ami design is fine-grained 
architecture (lower level). 


Analysis Pattern, Archttectiiral 
Pattern, and Design Pattern 

Many kinds of patterns exist. And more often than not, 
there are different definitions for the **same" kind of pattern. 
A prime example is die term “design pattern'' which 
sometimes denotes patterns in general and sometimes a 
particular class of patterns (as it does in this article). 

As a basis for further discussion, we quote five 
definitions from the literature: 

Analysis Pattern 

Richter [16, p. 344]; 

'"An analysis pattern is a way of solving a problem in 
a particular problem domain/' 

Architectural Pattern 

Richter U6, p. 3451: 

"An architectural pattern is a probleni-indepe^idenl 
way of organizing a system or subsystem. It describes a 
structure by which the different parts of a system are 
organized or interact ." 

Buschmann et at. [6, p. 12]: 

'An architectural pattern expresses a fundamental 
stmctural organization schema for software systems. It 
pnmdes a set of predefined subsystems, s[)ecifies their 
responsihilities, and includes ndes and guidelines for 
organizing the relationships between them .'' 

Design Pattern 

Richter [16, p. 345]: 

"A design pattern is a solution to a small problem that 
is independent of any problem domain. It represents an 
attractive solution to a design problem that could occur in 
any kind of application. We same design pattern can be 
applied in areas as diverse as order processing, factory 
control, and meeting room scheduling." 

Buschmann et al. [6, p. 131: 

"A design pattern provides a scheme for refining the 
suhsystein or components of a software system, or the 
relaHonsbips between them. It describes a commonly- 
recurring stmcture of communicating components that 
sohjes a general design problem within a particular 
context ll I ]." (Note: here, “component" means software 
entities in general, not components in the more narrow 
sense of cQmpc;)nent-c:>riented programming [22, CS99]-) 

Examples 

Example analysis patterns can be found in Fowler’s 
book [8] and on his homepage [9f 
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Probably one of the most successful architectural 
patterns is the Layers [6, p, 31]: 

Layers architectural pattern helps to structure 
applications that can be decomposed into groups of 
subtasks in tvbich each group of subtasks is at a particular 
level of abstraction. ” 


Client 

uses 

LayerN 







LayerN-1 


highest level of absiractiort 


Uiyerl 


lowest level of abstraction 


Figures- Layers[6]. 

Well-known examples of the Layers pattern are the 
ISO Open System Interconnection (OSD model (layers: 
application, presentation, session, transport, network, 
data link, and physicaD or the Java platform (host 
operating system, Java run-time environment, Java 
application). Buschmann et ai [6] and Szyperski [24J 
discuss several variants of Layers. 

We do not need to discuss this pattern any further 
as you are most certainly very familiar with this 
fundamental architecture. And even if you are not 
impressed by the Layers at all, it is an excellent 
example: Patterns are about sound solutions to realistic 
problems, not about the most elaborate solution to an 
exotic probiem. 

The Adapter pattern is one example of a design 
pattern. Another one is the Wrapper Facade [201: 
''The Wrapper Facade design pattern encapsulates the 
functions and datapjrovided by existing non-objectoriented 
APIs within more concise, robust, portable, maintaifiable, 
and cohesive object-oriented class interfaces ." 



Figure 4,: Wrapper Facade [20]. 



no complicated reseller 
rebates 

»no special terms or 
conditions 
• no tiidden cbarges 
« no ‘‘got tbls If you 
buy this” 

• no boofts» catchy, 
installatmn fees, or 
well, any other buill 


PowerMax is all about choices. With our crack 
sales team always willing to consult and advise 
on everything Macintosh® combined with the 
ability to order on line, via email, fax or on the 
phone, we offer what you want, when you want, 
and at the price you need. 


The G4 ''BulldoioT^ Bundle 

New G4/400 
Upgraded to 128 MB 
RAM • 10 GB HD 
DVD-ROM * 56k 
Modem *15'' Apple LCD Display 
Canon BJC-2100 inkjet 
$2099 after Canon printer rebate 




The ilVIac"* “Bullseye" Bundle 

Refurb Bluebcny^ iMac 350 
Upgraded to 128 MB RAM 
6 GB HD 
CD-ROM 
j 56k Modem 
Canon BIC-2100 inkjet 
$799 after Canon printer rebate 




The iBook™ "Bulffighter" Bundle 

Refurb Graphite iBook 366 MHz 
Upgraded to L28 MB RAM 
6 GB HD * CD-ROM 
56k Modem * Graphite 
iBook carry case ^ 

* Canon BJC-85 portable inkjet 

$1699 



The PowerBooh^ -Bulldog- Bundle 

Refurb PowerBook 500 MHz 
Upgraded to 192 MB RAM 
12 GB HD - DVD-ROM 
56k Modem 
Curds Roadster Bag 
Canon BJC-85 portable inkjet 

$2999 


MHz 

AM # 

J 


Examjilss ol some ol our great CPU deals: 

Used T\mm 16/700/CD.$140 

Used 7000/90 32/500/CD.$159 

Used 8100/80 40/500/CD.$219 

Hew Blueberry iMac" 350 64/6/CO.$749 

Used 9600/200 64/2/CD.$874 

Ref Reby IMac" 450 OV 64/20/DVD.$1088 

Ref Indigo iMac'450 DV 64/2D/DVD.$1088 

New Grapbife IMac" 400 DV 128/13/DVD .$1188 

Used iBook’300 32/3/CD.$1199 

Used Blue&White G3/400 64/6/DVD/56k ..$1249 

Rel G4/45012B/2Q/DVD/Zip/S6k.$1749 

And literally bundreds more!.$Call 


Jut ask IB ahwl nir great deals HE 

• leiaega • Epsan • tgla • Can • OPS 

• Vreai • Atanle • Initio • Fanlaai • lacia 
•XndiilpGiiifl •SonyVST•FOiiKiLagH 

• ATI • Xoyspan • Mioatech • IDIIs mere 

TraiteUp 



^wtik 

rownMaxI 

We'll take pur OS computer 
in trade toward ttie purclme at 
new prodtict. Call one of otir expert 
consultants far full details! 


800 > 689'8198 

www.powermax.com 

meal: (503) 624-1821 • tm (503) 624-1635 
email: sales@poweiinax.com 

• FWoaallliaiiGlig • fMRILlIppioifflis • BosiKss 


notice. Plioesr 
{ash [feoounKM card 
oittetsstnctlv'/erifiedaga^^ 
fraudulent use. With use of 
cnsditcardaspapent 
CLEtomerac Wedges 


NAK 


Knowledge is Power 


SOTO prate are suDjed to 
Ivialsale. pirn are 
SmitedtDslotkon twid.AI 
brand or piDductims are 


AytfliUrmHi 


iwctiveholte. 




January 2001 • Ma(Tech 











































































As shown in Figure 4, the intent of the Wrapper 
Facade Is to keep an object-oriented application purely 
object-oriented even though it relies on a procedure- 
oriented library. Again, the pattern is about an easy-to- 
understand solution to an easy-to-understand 
problem.^—Nevertheless, the study of patterns is 
worthwhile: quite a few patterns discuss not-so-obvious 
(albeit highly elegant) solutions to non-trivial problems. 

Discussion 

First, note how Richter emphasizes the domain- 
specific nature of analysis patterns and the domain- 
independent nature of architectural and design 
patterns, (Riehle and Ziillighoven [18] make a similar 
distinction betw^een conceptual patterns and design 
patterns,) Do not take these definitions too literally, 
though. As Fowler remarks [10], an analysis pattern 
from one domain can prove useful in a completely 
different domain. And sooner or later, you will .stumble 
over deceptively contradictory patterns categories such 
as "security architectural patterns” or “GUT design 
patterns”. This can either mean that a set of general- 
purpose patterns has been collected for a particular 
domain, or that a pattern is domain-specific (e,g., for 
GUIs) but still general enough to be applicable in 
different situations within that domain (e.g., for 
different widgets). 

Next, both architectural patterns and design 
patterns are language independent. (Language 
dependent patterns are called iciioms [6] or 
programming paiter?is [18], by the way.) And 
architectural patterns are also paradigm independent. 
The layers in Figure 3 could each consist of a set of 
procedures, or .some could consist of classes and some 
of functions, etc. Design patterns on the other hand are 
typically object oriented. The Wrapper Facade is a 
border case. 

Finally, rotate Figure 4 by 90 degrees and you will 
see — the Layers (layers: Application, 
Wrapper Facade, Functions)! It should come to no 
surprise that design patterns refine architectural 
patterns. However, sometimes it is dHTiculc to detennine 
wliich design pattens to apply for the refinement. As we said 
in the introduction, patterns help capturing and passing on 
experience, but tliey do not make experience obsolete. 

To Probe Flirdeer 

A good starting point for pattern-related 
information on the Web Is the patterns home page of 
the Hillside group [12]. And many authors of the 
patterns community provide information on their 
personal home pages (e.g., Riehle [17] or Schmidt [19D. 

A must-read is Gamma ei al's Design Patterns [111. 
The publication of this seminal book triggered the 
intensive search for patterns that continues unabated 


today. Code examples are given in C++ and Smalltalk, so 
you may want to take a look at Lalonde's article [131. We 
hope that the authors will take the time to publish a 
second edition. This would allow them to modify the 
diagrams to be UML compliant and to extend the “Known 
Uses” sections with examples from the Java platform, 

A should-read is Buschmaon et al 's Pattern-Oriented 
Software Architecture [6] which pioneered architectural 
patterns. In newer publications, this book is also referred 
to as POSA 1, because other books with the same main 
title have been published or are in preparation. 

The patterns community has its own conference 
and publishes the proceedings in the Pattern Language 
of Program Design series [1]. 

One book you may want to take a look at as well 
is Brown et al.'s AntiPatterns [5], some sections of 
which are pretty good while others cannot keep up 
with the rest of the book. Whether amipatterns really 
are a concept of their own or just patterns whose 
template also includes a bad problem “solution” 
encountered in practice is debatable. 

Alas, now that patterns entered the mainstream, a 
few books are on the market that only try to cash in on 
a buzzworld-enabled title, 
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Writing Cross-Platform 
QuickTime Code 


Introduction 

As you know, QuickTime was 
originally developed to run on 
Macintosh computers. In the mid 
1990’s, Apple released a version of 
QuickTime (called ''QuickTime for 
Windows’") that provided support 
for playing QuickTime movies on 
Windows computers. While it was a 
significant step forward, this version 
had some severe limitations. Most 
importantly, it provided a playback 
engine only; there was no API for 
creating QuickTime movies on the 
Windows platform. Also, many of 
the APIs for playing movies back 
differed from their Macintosh 
counterparts. For instance, on the 
Mac, NewMovieController is declared 
essentially like this: 

MovleController 
NewMovieController (Movie 
theMovie. 

const Rect 

*movieRect, long someFlags): 


But under QuickTime for Windows, 
it had this declaration: 

MovieController 
NewMovieController (Movie 
theMovie, 

const LFRECT 

IprcMovleRect^ long someFlags* 

HWND hWndParent); 


Youdl notice that the Windows version took an additional 
parameter (hWndParent) and that the type of the second 
parameter was a pointer to the standard Windows rectangle 
type ( RECT), not the Macintosh rectangle type (Rect), 

Personally, I never wrote any code using the original 
QuickTime for Windows APIs, but 1 can imagine that it was 
something of a headache for experienced Macintosh 
programmers. Just flipping casually through the 
documentation is enough to convince me that it was 
probably impossible to develop any very interesting 
QuickTime code that would compile and link on both 
platforms. My guess is that anyone developing a QuickTime- 
savvy application for both Mac and Windows platforms 
probably had to maintain two separate source code bases. 

QuickTime 3.0 changed all that. It provided, for the first 
time, a set of APIs that were virtually identical — in both 
parameter lists and feature completenes.s — on Macintosh 
and Windows platforms. In other words, it is now possible 
to write Mac and Windows applications that use the same 
source code, at least for the QuickTime-specific portions of 
the application. If you’ve been following this series of 
articles for the past year, then you know^ that JVe placed a 
great deal of emphasis on developing code that is 
completely cross-platform. In this article, we’ll take a more 
in-depth look at some of the platform-specific issues that 
weVe considered only in passing up to now (such as 
working with multi-byte data and resources), 

The magic provided by the Windows version of 
QuickTime 3-0 was accomplished principally by a library 
called the QuickTime Media Layer (or, more briefly, 
QTML), The QuickTime Media Layer provides an 
implementation of a number of the parts of the Macintosh 
Operating System (including the Memory Manager and the 
File Manager) and the Macintosh User Interface Toolbox 
(including the Dialog Manager, the Control Manager, and 
the Menu Manager). QuickTime, of course, also runs on 
Mac OS X, which is a UNIX-based operating system. In 


Tim Monroe Ls pleased to report that Libra, his home-hatched baby lizard, is doing well and is happily gobbling up flies, 
spiders, and crickets. You can reach him at monroe@appIe.com. 
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this case, the implementation of the Macintosh Operating 
System and Toolbox managers is provided by a Iibrar>^ 
called Carbon. It should come as no surprise to learn that 
Carbon originally grew out of the existing work on QTML. 

We’re going to approach this article in this way: let’s 
suppose that weVe got a QuickTime-sawy application 
that runs under the ‘‘classic” Macintosh operating systems 
(that is, MacOS 8.x and 9.x). We want to see what we 
need to do to get it to run also under die various flavors 
of Windows (namely, Windows 95/98/ME and Windows 
NT/2000) and under Mac OS X. 

Endiaj^ Issues 

Let's begin this odyssey at the lowest (and sometimes 
most vexing) level, by considering the memory storage of 
multi-byte data. Motorola processors in the 680x0 family 
expect multi-byte data to be stored with the most significant 
byte lowest in memory. This is known as big-endian byte 
ordering (because the “big” end of the data value comes 
first in memory). Intel and other processors used for 
Windows machines expect multi-byte data to be stored with 
the least significant byte lowest in memory; this is known 
as littie-endian byte ordering. (See Figure 1, wliich shows 
the value 0x12345678 stored in both Motorola 680x0 and 
Intel formats.) The PowerPC family of processors supports 
both big- and little-endian byte orderings, but uses big- 
endian when running Macintosh software. 


function QTUtils_GetWmdowPositjonFfomFile, which 
returns the scored location of the cop-left corner of the 
movie window. 


Listing 1: Getting the stored position of a movie 
window 


QTU tils_GetWlndo wPosi Li on Pro m Fi le 

OSErr OTUtilsJetWindowPositionFroniFile (Movie theMovie, 

Point *theFoint) 

I 

UserDita myUserData = NULL; 

Point myPoint “ ikDefaultWindovX, kUefaultWindowYl; 

OSErr myErr = paramErr: 

// make sure wc'vc got a movie 
If CtheHovie “ NULL) 
goto bail: 

// get the movie's user data list 

tnyUserData = GetMovleUserData(theMovie): 

if (myUserData != NULL) i 

myErr = GetUBerDataltemCtnyUserData, irnyPoint, 

Slzeof (Point), F0tJH_CHAR_CODE (' WLOC *), 0); 
if (myErr = noErr) { 

my Point. V = EndianS16_BtoN(iiyPoint. v); 
myPolnt.b “ EndianS16_BtoN{ayPolnt.h): 

1 

) 

ball: 

if (thePoint != NULL) 

UhePoint = myPoint; 

return(myErr): 

} 


0x78 |0xS6 |0x34|0xiT 

Big‘endla n byte ordering L iltle-endia n byte ordering 

Figure 1: Big- and linle-eudian data storage 

Thi.s difference is important only in one instance, 
namely when a stream of data is transferred between the 
computer’s memory and some external container (such as 
a file). For instance, if we open a file that has its data 
stored in big-endian format and read a segment of it into 
memory, we should not operate upon that data without 
first making sure that we convert the data into the proper 
endian format for the processor we Ye running on. This 
conversion is known as byte swapping. Let’s consider a 
few real-life cases where byte swapping comes into play. 

Working with Movie User Data 

A movie’s user data is stored inside of atoms in a 
QuickTime file. When we call the function 
GetMovieUserData to get a movie's user data, the Movie 
Toolbox reads that atom into memory and returns a 
handle to that data to us. We can get a specific piece of 
movie user data by calling GetUserDataltem and passing it 
the type of data we want. For instance, we can retrieve 
the stored window^ location of a movie by reading the 
user data item of type 'WLOC’. Listing 1 defines the 


0x12 I 0x34 I 0x56 I 0x78 


Valentina 

object-relational database engine 


The fastest database engine 
_ for the Mac OS _ 

It operates IM's and sometimes a 1000 

times faster than other systems_ 


Valentina - scriptable ... $49 

- Inciude?i special features for Web Ctevelopers. 

- Glues for Frontier and Mac Perl. 

Valentina C++ SDK........ $499/$699 

- Cross-platform (Mac OSAVIN32); 


- bool ,b>1;e,shorl, I ong,floal.double,datedi me string3 LOB ,TEXT,Picture. 

- RegEx search* hdl text indexing, support mtematiotial languages. 

- SQL, random-access cursors. 

- MuUi-threading capable. 

- Record locking. 

- No runtime fees. 


Valentina for REALbastc plugin .....$199 

Valentina for Macromedia Director Xtra....$199/299 

Valentina for WebSlphon........ $299 

Valentina XCMD .........$199 


Make your application’s database operations blazingly fast! 
Order Directly WWW. paradigmasoft.com 

from Our Web Site Hosted b\' MacServe.net 


Download full featured evalution version| 



January 2001 • MacTech 

































You’ll be stuck in 
San Francisco’s heaviest 
traffic and loving every 
minute of it. 


At Macworld Expo SF 2001, we make it easier for all techies, novice and expert, to have a 
space as special as their ideas. Formerly Developer Central and Net Innovators, MacTech® 
Magazine presents MacTechfsmj Central — an exhibit at Macworld that showcases technical 
and developer tool/service companies for the Macmtosh in the biggest possible way. 
Macworld takes place in San Francisco, January 9-12,2001. Check out the exhibits at the 
show (Booth 3240) and on the web at: www.mactechcentral.com. 



Mi^cTecb is registered tradenmiis of Xpluin Corporation. MacTech Centmt is a sendee mark of Xldain Corporation. 
Other trademarks and coj^itigbts appearing in this prin ting renmin the [rnypert^^ of their respective holders. 






MacTech Central 
Sponsored by: 




metrowerks* 

Softwe^re StartB Hara M 



A.D. Software 
Active Concepts Pty Ltd 
Aladdin Knowledge Systems Inc 
Apple Developer Connection 
AvidTechnolgy, Inc. 
ComGraflx, Inc. 

CommonGround Softworks, Inc. 
Developer Depot 
Douglas Electronics, Inc. 
edition.net 

eSellerate / MindVision 
Late Night Software Ltd. 

MacTech Magazine 
Mathemaesthetics, Inc. 
Maxum Development Corp. 
Metrowerks Corporation 


Newnex 

Nisus Software, hic. 
Omni Group 

OpenBase International, Ltd. 
Preview Systems 
REAL Software, Inc. 
Rocky Mountain Ram 
Scientific Placement, Inc. 
Script Software International 
SNAP Innovation Software 
GmbH 

Softmagic, Inc. 
SoftPress Systems, Ltd. 
Sustainable Softworks, Inc. 
UNI SOFTWARE PLUS GMBH 
WebEx 








With only rare exceptions, movie user data is stored 
in big-endian format. So once weVe read in the data 
stored in the “WLOC’ user data item, we need to convert 
that data from big-endian format into naHve-endian 
format (chat is, the native format of the processor weVe 
running on). As you can see, 
QTLftl!s_GetWindowPositionFromFile uses the macro 
EndianS16_BtoN to convert the signed l6-bit data from 
big- to native-endian format. This macro is defined in the 
file Endian.h, like this: 

TARGET_KT_BlG_ENDlAKr 

#define EndianSl6_BtoNCvalue) (value) 

^^else 

^define EridiaiiSl6_BtoH(value) 

EndianS16_BtoL(value) 

#endif 

In other word.s, if %ve are running on a big-endian 
processor, then EndianS16_BtoN does nothing. But on a 
little-endian processor, EndianS16_BtoN is replaced by the 
macro EndianS16_BtoL, which in turn is replaced by the 
macro Endian16_Swap: 

/Mefine EndlanS16_BtoL(value) 

{(Sint 16)Endianl6_Swap(value)) 


Finally, Endian16_Swap is defined like this; 

#define Endianl6_Swap{value) \ 

{((((UIntl6)vaiue)<<8) 6. OxFFOO) | \ 

((((UlntlS) value) >>8) h 0x0OFF)) 

If you work through this, you'll see that Endi3n16_Swap 
simply swaps the high-order byte with the low-order byte, 
which is just what we expected. The macros for handling 
32- and 64-bit values are of course more complicated, but 
do pretty much the same thing. 

Here are a couple of things to keep in mind to help 
you decide when you need to worry about endian issues: 

• Byte swapping is required only for multi-byte data 
(that is, data that's l6 bits or larger). For smaller 
chunks of data, we don't need to worry about this 
issue. So. for example, if we retrieve a user data item ^ 
whose data is a Boolean value, we don’t need to swap 
any bytes. 

• Byte swapping is not required for C or Pascal strings, 
even though these are typically multi-byte. Strings are 
interpreted as arrays of single-byte characters, so they 
are identical on big- and little-endian architectures. 

• Byte swapping is required only when data is to be 
transferred between RAM and some external container 
(such as reading data from or writing data to a file). 
For in-memory calculations or moving data between 
buffers, we don’t need to worry about the endianness 
of die data. 

• Note that the Endian16_Swap macro evaluates its 
argument several times. It would be a bad idea, 
therefore, to use increment (++) or decrement (—) 
operators in these macros. (To be safe, don't use these 
operators in any macros, since the definitions of the 
macros may change. Believe me; this has bitten me 
more than once.) 

In general, any data stored in a QuickTime file is in 
big-endian format. This includes movie user data, data in 
atoms and atom containers, stored sample descriptions, 
and media data itself. In some rare ca.se.s, media data may 
be stored in little-endian format, but the appropriate 
media handler should insulate us from having to worr>^ 
about that. 

Reading and Writing Resource Data 

Data stored in Macintosh resource files is always big- 
endian. There is, however, an important difference 
between the data returned to us by the File Manager and 
the data returned to us by the Resource Manager. To wit: 
the Resource Manager always gives us native-endian data. 
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In other words, if we use Resource Manager calls to open 
(for instance) a *pnot’ resource, we can read the fields of 
that resource (which, as w^e’ve seen in earlier articles, has 
the structure of a preview resource record, of type 
PreviewResourceRecord) without having to flip any multi- 
byte data. The same holds true of writing data to a 
resource: we give the Resource Manager a handle to a 
block of native-endian data and it will ensure that the data 
actually written to the resource file is in big-endian format. 

This automatic byte .swapping is accomplished by a 
piece of code called a resource flipper. A resource flipper 
takes a handle of data and flips the muld-byte data fields 
in that handle, in place. Of course, a resource flipper 
needs to have intimate knowledge of the structure of the 
resource weTe handing it. QTML includes resource 
flippers for these resource types: ‘ALRT’, ‘BNDU, 'cdci\ 
‘cicn\ 'duf, *CNTL^ ‘cpix^ ^crsr’, *CURS\ ^DITL’, ^DLOG’, 
FREF^ -fttr, ‘gnhf, ‘icl4\ 1cl8’, 1CN#’, 1CON^ 1cs4\ 1cs8’, 
'MENA’, ‘MENU*, 'nini\ 'pnot, 'qfmf, 'qmtr’, ‘qtet\ 
'snd *, ‘stg#*, ‘stgp*, 'STR ^ ‘SIR#’, 'styf, TEXT', ‘thar\ 
‘thga’, ‘thnd’, ‘thing’, 'thnT, ‘vers*, ^WIND*, and ‘wxim*. (This 
list is current as of version 4.1.2.) 

But what if we w^ant to work with a resource that isn’t 
one of these types (say a custom resource used only by 
our application)? Here we have at least two choices. First, 
we can just make a local copy of the fields of the data in 
the resource handle returned by the Resource Manager 


whenever we need to access them and then flip those 
fields ourselves. For instance, let’s suppose that we have 
a custom resource of type ’CHAP* that consists of a signed 
16-bit count followed by that number of signed 32-bk 
integers (perhaps to record the start tiores of the chapters 
of our movie). We might use this data structure to help us 
read and WTite the resource data: 

struct ChapterResourceJ^ecord I 
SInti6 fNumChapters: 

SInt32 fChapters [1] : 

]; 

typedef struct ChapterResourceRecord 
ChapterResourceRecord; 

typedef ChapterReBourceRecord ‘ChapPtr '*ChapHdl; 

We can open a resource of type 'CHAP* and get the 
number of chapters in the resource like this: 

ChapBdl myChapters “ NULL: 

myChapt ers = tChapHdl) GetResource fE0UE_CHAR_C0DE (‘ CHAP') * 

kMyChapResourceID); 

if (niyChapterB ]= NULL) 

myNumChapfi = EndianS16_BtoNU**niyChapters)-fNuiQChapters): 

Another way to handle this is to tell the Resource 
Manager how to flip the data in our custom resource. 
Then it can do all the necessary work for us whenever we 
read or write a resource of that type, leaving us to work 
always with native-endian data. To do this, we install a 
resource flipper for our custom resource type, by calling 
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RegisterResourceEndianFifter, which has this declaration: 

OSErr RegisterResourceEndlanFilter 

(ResType theType^ ResourceEndianFilterPtr 
theFilterProd): 


As you can see, we pass RegisterResourceEndlanFilter ihe 
type of our custom resource and a p<Hnter to our resource 
flipper. The data type ResourceEndianFHterPtr is declared 
like this: 

typedef OSErr ('ResourceEndianFHterPtr) 

(Handle theResource, Boolean 
currentlyNativeEndian.) : 

For our custom 'CHAP' resource, we could write our 
resource ilipper as shown in Listing 2. 

Listing 2 : Flipping the data in a custom resource 
type 

Ql’X R_Cha p te r Reso urctF I i p per 

OSErr QTXP_ChapterRe 30 urceFUpper [Handle theHandle, 

Boolean currentlyNativeEndlan] 

I 

Ptr myDataPtr ^ NULL; 

short tnyNuinChaps “ 0; 

short myCount; 

if f[theHandle ” NULL) || [’theHandle = NULL)) 
retumtnllHandleErr); 

// set htiw many long^s arc in iliis rtwniax thu 

myDataPtr “ *theHandle; 

myNumCha ps = '(short *)my 0 a t aPt r; 

// Lf wc'rc nippinf? fmm big- to nut!Vf-endian, wc ncird tti flip myNumtihaps 
// or else our loop limit will be tetribly wrong 
if [IcurrentlyNatlveEndian] 

myNumChaps = EndianSl6_BtoN(myNumChap3); 

// first, flip the fNumChapiers field. 

•(short •)myDataPtr = Endian!6_Svap(‘(short *ImyDataPtr)i 
myDataPtr +“ slzeof(short): 

// now (lip the eh;ipier data 

for [myCount ” U; myCount < myNumChaps; inyCount++) ] 

•(long * }tiiyDataPtr = Endian32_Swap[" (lorig *) myDataPtr ] : 
myDataPtr +“ sizeof(long): 


return(noErr): 

I 

The sectind panimcter passed to our resource flipix^r, 
cunrentlyNativeEndian, is a Boolean value tliai indicateii whether 
the data in the handle s|X"cified by tJie first paranieter Ls in nadve- 
endian Ibnnat. If ifs naiive-endian, tlien wc can read tJie dzita in 
that handle and use it wiihcaii llrst converting it. OtlierwlscL we 
need to convert any of tliat data tluii we use in our flipper. In 
QTXP_ChapterResourceFiipper, for instance, we need to flip die 
16-bit count field if ifs not already in nadve-endian format, since 
we use dial value in the for loop. 

We can install our custom resource flipper like dii.s: 

myErr = 

RegisterResourceEndlanFilter(F 0 UR_CHAR_CQDEC'CHAP'). 

QrXP_ChapterReso'iirceFlipper) : 


Keep in mind that resource flippers are necessary only on 
non-Macintosh platforms ^ because there is no need to 
byte swap resource data on the Mac, (In other words, the 
resource storage format and the memory storage format 
are the same on Macintosh computers,) 

Occasionally we might need to knt)W whether a 
resource flipper is installed for a particular resource type. 
We can determine this by calling 
RegisterResourceEndianFilter to try to install a new 
resource flipper for that type. If a resource flipper is 
already installedj RegisterResourceEndianFilter returns the 
value 1; otherwise, it returns noErr, 

The QuickTime Media Layer 

As we learned earlier, the QuickTime Media Layer is 
a Windows implementation of those parts of the 
Macintosh Operating System and the Macintosh User 
Interface Toolbox that are used by QuickTime. In effect, 
QTML provides a sizable chunk of a Macintosh ROM 
cleverly packaged into a dynamic-linked library 
(QuickTlme.qts). This is required to run QuickTime on 
Windows computers because QuickTime APIs are riddled 
througli-and-through with MacinUish data types such as 
handles, resources, and Pascal strings. Also, QuickTime 
internally calls a large number of Mac OS and Toolbox 
routines, such as NewHandle, GetResource, NewControl, 
and the like. As we might say, you can take QuickTime 
out of the Mac, hut you can't take the Mac out of 
QuickTime; so we need to drag a g()od lift of the Mac OS 
and Toolbox anywhere we want to run QuickTime. Thafs 
what QTML provides on Windows (and what Carbon 
provides on Mac OS X), 

Q'l'ML is a rcx'k-solid prcxJuct, I'he most important 
evidence for this is that it s possible tt.) write large chunks of 
QuickTime code on the Mac that alstj compile, link, and run 
on Windt)ws (assuming you’ve paid attention to issues like 
endianness of niulti-l^yte data). It just works! Ifs important to 
understand, however, that there are limitations to what you 
can do witli QTML, and we’ll consider some of those 
limitations in tliis section, llie main thing to keep in mind is 
that the QuickTime Media Liyer is not designed as a general- 
purpose tool for getting any and all Mac OS or Toollxjx 
functions to run on Windows. Rather, ifs designed to support 
tfiose pans of the Mac OS and I'oolbox tliat are needed to run 
QuickTime. If you remember nothing else from this article, at 
least remember this: QTML is no! a pontn^ iayen 

Avoiding Namespace Collisions 

One of the first issues we run into when porting our 
Macintosh-based QuickTime code to Windows is a small 
number of collisions in the function namespace. That is to 
say, some of the Mac OS and Toolbox functions have the 
.same names as similar W^indows functions. For instance, 
both Mac and Windows provide functions named 
ShowWindow. If we try to compile our Macintosh code 
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unchanged, well get a compiler error like this: 

Error : cannot convert 
'struct GrafPort to 
'struct HWND_ 

QTTimeCode.c line 426 ShowWindov(inyDialog) ; 

Luckily, the Mac header files now contain alternate names 
for these functions for non-Mac targets. In general, the 
new forms of the names simply contain the prefix “Mac", 
to signal that they are the Macintosh versions of these 
functions. For instance, the Mac version of ShowWIndow 
has been renamed as MacS how Window. Some other 
renamed functions are MaoSetPort, MacInsertMenu, 
MacSetRect, MacOffsetRect, MacPtInRect, MacSelCursor, 
and MacCheckMenultem, (This list is by no means 
exhaustive.) As a rule of thumb, if you get a compiler 
error where the compiler tries to convert Mac data types 
to Windows data types, try adding the prefix “Mac” to the 
function name. 

There were also collisions in the names of header 
files^ The Mac OS file originally called Windows,h (which 
contains the public API for the Macintosh Window 
Manager) was renamed as MacWindows.h (to avoid 
conflict with the Windows header file windows.h). 
Similarly, the file Types.h was renamed as MacTypes.h, 
Errors.h was renamed as MacErrors.h, Memory.h was 
renamed as MacMemory.h, and Help.h was renamed as 
MacHelp.h, (i believe that this list is exhaustive.) 
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To my knowledge, the only data types renamed to 
accommodate the Windows APIs were the QuickDraw types 
Polygon and Region (to MacPolygon and Mac Region, 
respeaively), and T have found only one constant in the Mac 
headers that causes problems when compiling code under 
Windows, Tlie file MoviesFormat.li contains these constants: 


enum i 

M0VIE_TYPE 

TRACK_TYEE 

MEDIA^TYPE 

VIDEO_TYPE 

SOUKD_TYPE 


E0UR_CKAR„C0DE('moov*), 
E0UR_CKAR_C0DE(■trak *). 
F0UR_CHAR_CODE( - India') . 
E0UR_CHAR_CODE i 'vide'). 
F0UR_CHAR_C0DE('soun *) 


Unfortunately, the Windows header file winioctl.h contains 
an enumerated type called MEDIA_TYPE (for various 
types of device media). Compiling with both these header 
files results in an “illegal name overloading" error. When 
building code using Microsoft Developer Studio on 
Windows, 1 usually don’t include the file winioctl*h. But 
when using CodeWarrior on the Mac with the 
precompiled Windows headers, the easiest way to avoid 
the collision is to edit MovlesFormat.h to comment out the 
definition of MED1A_TYPE. Cheesy, but true. 


Working with Files 

Windows, of course, provides its own functions for 
opening files (for instance, CreateFtle), When working 
with movie files on Windows, however, it’s usually easier 
to use the routines provided by the Macintosh Standard 
File Package and File Manager, The main reason is that 
these functions use file system specifications (of type 
FSSpec) to refer to files, w^hich are also used by 
QuickTime functions like CreateMovleFfle and 
OpenMovleFile. For instance, we can use the following 
lines of code to elicit a movie file from the user and open 
the selected file: 

TARGET_ 0 S_WIN 32 
// prompt the user for a file 
myTypeList[ 0 ] = MovieFileType; 

StaiidardGBtFllePreview(NULL, 1. myTypeList, 4myReply); 
if (JmyReply.sfGood) 

return[userCanceledErr): 

// mke an FSSpec record 

FSMakeFSEpec (Ot OL, myReply,sfFile.name. &jJiyFSSpec); 
OpenMovieFiis(iinyFESpec. SinyRefHuiii. fsRdWrPeria) ; 

/^endif 


This snippet of code also reveals that the FSSpec data 
type is defined differently on Mac and Windows. On 
Windows, the name field contains a full pathname of a file, 
and tlie parlD and vRefNum fields are ignored. Also, like tlie 
Mac version, the name field should contain a Pascal string, 
not a C string. QTML provide.s a useful function for 
converting a C-style pathname into an FSSpec: 

KativePathNameToFSSpec f"c:WmyMovie,mov", SmyESSpec♦ 

kFullNativeFatli) ; 
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We can also use the File Manager to openj create, and 
manipulate files that are not mc>vie files. You may recall that 
in an earlier article Cdn and Out” in MacTecb, May 2000), 
we defined a function QTDX^GetExporterSettingsFromFile 
that used another function, QTDX_ReadHandleFromFile, to 
read the data in a file into a handle. 
QTDX_ReadHandle From File is defined in Listing 3. 

Listing 3: Reading a file’s data into a handle 


QTDX_ReadHa n die FromFiie 

Handle QTDX„ReadHandleFromFile {FSSpecPtr theFSSpecPtr) 

I 

Handle myHandle - HULL: 

short myRefHuin = 0: 

long mySize “ 0: 

OSErr myErr - noErr: 

// open the file 

myErr “ FSpOpenDF(theFSSpecPtir. fsEdWrPenn, SmyRefNuiri} ; 
if (myErr ^ noErr) 

myErr “ SetFPos(myEefNuiD, fsEromStart, 0): 

// get the sl?:e of the file dau 
if (myErr “= noErr) 

myErr “ GetEOF(myRefHimi, imySlze): 

// allwate a new handle 
if [myErr ™ noErr) 

myHandle = NewHandleClear(mySize); 

if (myHandle ” NULL) 
goto bail: 

// read the data fttm tiic file into tlie handle 
if (myErr ^ noErr) 

myErr - FSRead(myRefNumH fiimySize. *myHaridle); 


bail: 

if [myRefNurcL 0) 
FSGlose(myRefNum): 

return[myHandle]: 


This is all pretty straightfon\'ard File Manager (and 
Memory Manager) code, and it works as well on Windows 
as it does on Macintosh. 

Working with Resources 

The Resource Manager, which reads typed data from 
a resource file, also works very well on Windows. 
Perhaps the biggest annoyance when working with 
resource files on Windows machines is getting them there 
in the first place. IVe found that some means of 
transferring resource files from Macintosh computers to 
Windows computers don’t w^ork very well or require 
additional steps. For example, if I copy the Macintosh 
resource file Mac Application, rsrc onto a floppy disk and 
then mount that floppy disk on a Windows machine, the 
file MacApplication.rsrc is usually 0 bytes in size. To find 
the actual resource data, I need to look inside a folder 
called Resource. frk, where the resource file now^ has the 
name Macapp-hrsr. Nor is copying resource files across a 
network much better. If I mount a Window^s disk on my 


Macintosh computer and drag the file MacAppfication.rsrc 
to the Windows disk, two files are created on the 
Window^s machine, MacApplication.rsrc (which again is 0 
bytes in size) and Mac Application, rsrc.# Res (w^iicli is the 
actual resource file). 

Perhaps the most reliable course is simply to build ihe 
re.source file on Windows from a .r file (which, being a 
normal text file, is easy to transfer from machine to 
machine). The QuickTime SDK includes the too! Rez for 
converting .r files into resource files. We can execute this 
line of code in the DOS Console to create a resource file: 

QtiickTlineSDK\QTDevWin\Tools\Rez 

-i "QuickTiii5eSDK\QTDevWin\RInclitdes" -i . 
QTShell.r -o QTShell.qtr 

Here, Rez converts the resource descriptions in the file 
QTSheIf.r into resources in the resource file QTShell.qtr 
(looking in the current directory and in the directory 
QuickTimeSDK\QTDevWin\Rlncludes for any included .r files). 

The output of the Rez tool is typically a file with the 
extension “.qtr'’, wdiich is the preferred extension for 
resource files that are to be handled using QTML. As we 
see, an application whose name is QTShell.exe w'ouid 
have a resource file whose name is QTShell.qtr. On the 
Macintosh, when an application is launched, the 
application’s resource file is opened automatically and 
added to the resource chain. But on Windows this is not 




application 

cornpciLola enrtmci Fair - 

PTiHuy addsd ; L vv 

re'pod-wrhor 1 

interlay. UfC iviiB ^ 

hE^-dil ■ ynr - ' c . - 0 

i Cross-Platform C++ 

- fPP2fyF€ puts your " ^ 

^ PowerPlant " 
applications on ,,, i.,,,,, 

compatible! ■ ij/- - P^ ntadi. -Y':d! 

mai4 addcL Windows^ ^ ^ -u:. 

platfcrrvf reporf-wn Pic --l • wi 

MFC : ‘ -■ ■ 

Lip handling ' , - r-i >r in 

cf-^ www.oofile.com.au 

mIHionft ot server nne v r.. r,. riif-: lU 

Mbc, V\^incfQw:i ^ Unix; Drilribaac applit ‘ r:n gi rrAiatjnn 
frmi* AppMrikof. d-Base compatible engine. -v- c l 

P\uh ii>lerfuce wit!) many ^rid^c i ,. ' ■ cm - 

piaHorrr: graphing; Crcs^i-plattoim report-wa /’ :' 

HTML output, PowerPlanl Tf)tedace MFf; intend -.-v 
io-U5e API; croaS’pfattorm file L idling nd ntr* 
tiOr^jiiGn; sonrc€> cobr^[ to ‘ --ir ’nnlc nsu 

multi-user royalty free; si^pport^ miHkvis Y i 
and stafidalon^^ version^: fun ol lAou Winrfer. 3i 

Database applicallon generalion from AppC aker d- 
compatiWe euglfie: >1fou cir : vC will- 

marry audtrc! features, cress-platform .MapOThy 


JAMUARY 2001 • MacTeCH 













The products you need, with the prices 
and service you des<^o... guaranteed. 









REALbasic 2.1 


Code Warrior Pro 6 


Power Tools for Programmers! 
NEwn 


CodeWarrior for Mac OS is a powerful inteerated 
development environment that includes a fully object- 
oriented application development framework called 
PowerPlant. With Code Warrior for Mac OS you can quickly 
develop reliable, professional quality applications that 
execute on Classic Mac OS. or OS X. 




ONLTl 


REAUbasic is the programming tool for ''the rest of us. ' Each 
window type, control, and menu is preconfigured and instantly 
works as it should The drag and drop Window Editor allows 
you to quickly and easily create your application's interface so 
you can focus on the important part-your creativity. Includes 
900 page manual, e>tamptes and tutorial on CD ROMl The 
professional version has all the power of the standard, plus 
database support and allows you to cross compile your code 
for Windows with a single click! 

As low as 




VOODOO Server 


VOODOO Server is a version controi system for software 
developers using Metrowerks CodeWarrior under Mac OS, 
VOODOO Server and the corresponding VOODOO clients [the 
included CodeWarrior VCS plugHn and the VOODOO Admin 
application} are designed to offer reliable and robust version 
control features while minlmi 2 ing the administrative overhead 
that usually accompanies version control if you're a single 
programmer or managing a team of developers, version control 
can make or break your proiect. Do it right, with VOODOO 


Spotlight 


Spotlight is the first Macintosh '‘Automatic Debugger^ ft can 
automatically locate run bme errors in your code and display 
the offending source code tine, Unlike simitar tools on other 
platforms Spotlight is easy to use. No source code changes 
are necessary for application debugging. Spotlight can 
automatically check for wild pointers, memory leaks, 
overwrites, underwrites. Invalid dereferencing of handles, and 
even toolbox parameter validity checking “ spotlight knows 
Macintosh verifying parameters to over 400 toolbox calls. 


Resorcerer is the only supported general-purpose resource editor 
for Macintosh. Relied upon by thousands of Mac developers, 
Resorcerer features a wealth of powerful yet easy to-use tools for 
easier, faster, and safer editing of Macintosh data hies and 
resources Whether you have to parse a picture, debug a data fork, 
design and try out Balloon Help, create a scripting dictionary, create 
anti-aliased icons, design and edit a custom resource with 40,000 
Helds in it, create C source code to run a dialog, or any of hundreds 
of other resource-related tasks, Resorterer's magic will quickly save 
jou hme and mgn^. 


$189 


cn?r 


One of the most flexible and powerful development 
environments on the Macintosh today! Easily create programs 
with the visual program editor, drop into the BASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly with the Macintosh toolbox. The 
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to all of the power of the Macintosh toolbox! 
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Master the Web! 



Monitor the bandwidth usage of up to live different machines on your 
network! Do you need to upgrade yoor Webserver? How hard is your 
eMail server wc}rking? you getting all the bandwidth you're 
paying for? Not only can CyberCauge answer all these questions, 
new features allow CyberCauge to eMail or page your network 
device becomes unresponsive r passes a threshold of usage you 
define - an essential first line of defense for early detection of dental 
of service attacks and necessity for warning you and tracking quality 
of ISPs that may have brown outs and shutdowns. 


WtebSTAR Server Suite is a tomplete set of powerful and easy- 
tCHUse Internet servers for the Mac OS. Effortlessly serve web 
pages, host email accounts, publish databases, and share files ■ 
all with a single application on one Mac! WfebSTAR Server Suite 
is perfect for Internet or Intranet serving, single or multiple 
sites, small I and large businesses ■ it's power and eases?f-use 
saves ariy organization time and money. 


Funnel Web Is the ultimate web analysis solution for 
professionals. Spedficaliy designed for profiling web site usage 
and monitoring customer usage patterns, Funnel V'feb is ideal for 
examining server performance and online effectiveness. Funnel 
\Ateb can analyze log file formats From any server, V\tebSTAR. 
WebTen, even Unix or NT hosted ervers. Discover the most 
popular pages on your site, track server loads 6t optimize server 
performance, profile visitors based on organization, domain 
narne, country, browser, etc. Funnel Web does it all[ 


NetBarrier offers a Personal Firewall. Anti vandal protection, and 
Internet Rltering. Protect your machine from intrusions by Internet 
or AppleTalk. Incorrect passwords and Individual actions are 
logged, you are alerted to hostile actions, and intruders are easily 
isolated- Internet Filtering allows you to be sure that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer - the content itself is filtered before 
any transferi (Rated 4 mice by Macworld Magazine) 
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NetBarrier 


...and great hardware solutions! 


2 USB PCI Card 


Add two US8 ports to your older Macintosh. Connect up to 
127 devices to the Universal Serial Bus (USB) that Is 
Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controliers, printers, 
scanners — connect them all to your current computer. 
Installs in minutes! 



Matsense USB Full Siie Keyboard 


Just plug this keyboard into your Mac and start typingl The 
UKa^SOO keyboard from Macsense is designed to get you 
typing quickly and easily, without any hassle or ccHnpatibility 
worries. It features two tone translucent desigr. colored to 
match your favorite flavor of Macintosh. It offers soft touch 
with positive tactile feedback and build built in USB port on 
either side of the keyboard. Includes a 5' USB cable and Is 
100% Macintosh compatible, simply plug and play, as easy 
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as Macintosh! 


Dr. Bott Moni Switch APB or USB 


Do you need 4 monitors and 4 keyboards for your 4 servem? 
With Dr. Efott Moni-Switch you can connect a single keyboard 
and monitor to up to 4 machines at once! A simple flick of a 
switch directs the video Input and keyboard commands to the 
appropriate CPUI Available in USB and ADB models^ with 2 
or 4 machine support and bundles with USB PCI cards so 
you can mix and match USB and ADB machines with the 
same Moni-Switchl Great for programmers to do back 
ground compiles, ideal fer server rooms overcrowded wtih 
monitors and keyboards! 
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Macsense Internet Sharing Router’ 


Looking to get your whole office online without shelling out 
thousands of dollars? If so, the XRouter Internet Sharing 
Flub offers the perfect solution. This amazing Ethernet-to- 
Ethernet hub connects an entire network of up to 252 users 
to the Internet using only one ISP account and one Cable or 
DSL modem! 

































the case. So if our Windows application uses any 
Macintosh-style resources, we need to explicitly open the 
application's resource file, as illustrated in Listing 4. 

Listing 4: Opening an application's resource file 

WiaMain 

myLengtb = GetModuleFlleiiaiiietNULL. MAX_PATH): 

If {myLength 1= 03 [ 

NativePathNameToFSSpec(myFi1eName, &gAppF3Spec. 

kFullNativePath)i 

gAppResFile = FSpOpenResFlle(SgAppFSSpec, fsRdWrPerm): 
if (gAppResFile 1“ kruvaiidFileRefNum) 

LfaeResFlle (gAppResFlle): 

] 

Here, we retrieve the name of the file that holds the 
application, create an FSSpec for that file^ and then pass 
that FSSpec to the Resource Manager Function 
FSpOpenResFile. Once this is accomplished, we can use 
other Resource Manager calls (like GetResource) to use 
the resources in that file. 

There is one final issue to consider. On Macintosh 
systems, a data fork and its associated resource fork 
have the same name and appear in the Finder as a 
single file. On Windows, otir application and its 
resources have different names and appear to the user 
as two different files. When we ship an application to 


the user, it’s better to combine both of these files into 
a single file. The QuickTime SDK includes the tool 
RezWack, which appends the resource file to the 
executable file (and also appends some additional data 
to alen QTML to the fact that the .exe file contains the 
resource file). We can use RezWack to combine our 
.exe and our .qtr flies like this: 

QuickTiroeSDKVQTDevWiEMools\ReaWack -d QTShell.exe 
■t QTShell.qtr -o TempNaiiie.exe 
del QTShell.exe 
ren TenspName.exe QTShell.axe 

RezWack does not allow us to overwrite either of the 
two input files, so we need to save the output file 
under a temporary name, delete the original .exe file, 
and then rename the output file to the desired name. 

Even if we have Rezw^ack'ed our application's 
resource file into the executable File, we still need to 
explicitly open the resource file; so our applications 
should include the code in Listing 4, whether the 
resource file Is a separate file or is included in the 
executable file. 

Working With Modal Dialog Boxes 

Okay, it’s perhaps not all that surprising that the 
File Manager and the Resource Manager run pretty well 
on Windows under QTML. But, for me at least, it is 
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fairly surprising that QTML provides extensive support 
for key parts of the Macintosh User Interface Toolbox, 
including the Window Manager, the Dialog Manager, 
the Control Manager, and the Menu Manager* Certainly, 
if the goal is to support running QuickTime 
applications on Windows computers, then there needs 
to be support for user interaction, since QuickTime 
and its components can display dialog boxes to show 
information to or get information from the user. Let’s 
see what issues arise when porting our Macintosh 
dialog box code to Windows. 

A dialog box typically contains some small number 
of controls (buttons, check boxes, edit-text boxes, 
pop-Lip menus, and so forth)* Controls in modal dialog 
boxes work very well, with minimal cross-platform 
dependencies. For example, in the previous article 
(“Timecode", last month) we displayed the modal 
dialog box shown in Figure 2. 



Figure 3* QTTimecode^s Timecode Options 
dialog box (Windows). 



Figure 2: QTTimecode's Timecode Options 
dialog box (Macintosh). 

The code for displaying this dialog box and for handling 
events in this box works unchanged on Windows. Figure 
3 shows the Windows version of this dialog box. 


Nonetheless, I did need to make a few changes in the 
original Macintosh source code to achieve this cross-platform 
parity’. First of all, 1 needed to adjust the way in which the 
plus sign (+) and the rectangle surrounding it were drawn. 
The code I originally inherited did something like this: 
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Professional Macintosh & Internet Development 


Always Thinking’s professional developers will 
help you meet your Macintosh and internet 
deadlines! So if you’re... 

* on a tight deadline and need additional talent 

* losing valuabie deveiopment time debugging 

* having trouble finding good developers 

... Always Thinking’s team of experienced 
programmers will provide you with a timely and 
affordable solution. 

We deliver more than code — a complete project. 
Our software engineers work with you to: 

I • Create clear, solid project specifications 

■ Design and develop your application or web site 
■Tune and optimize your software's performance 

* Thoroughly test your application or site 

* Completely document your project 

* Provide training to your team 


Commercial Product Development 

Do you have an exciting idea for an application? 
Turn to Always Thinking to make it a reality. We 
have firsthand experience developing and shipping 
award-winning commercial applications for our 
clients and our own Thinking Home, a 2000 
Apple Design Award winner. 


Web Site Design & Development 

Get a sound e-commerce system tailored for both 
your immediate needs and long-term growth. Our 
engineers can develop the Internet applications to 
transform your company into an e-business. 

Successful web sites are more than graphics and 
code. We have the Internet marketing know-how to 
ensure your site is an effective business tool. 


Realize substantial savings by moving to online 
pre-sales information, ordering and support. 



Tell us about your project, toll-free 


g. (800)556-9559 

^ (843) 986-0308 

Always Thinking, Inc. 
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Beaufort, SC 29902 
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Listing 5s Drawing a user item (original version) 

QTTC_GctTi meCoJc Opti (ins 


KodalDialogCgModalFilterUPP, : 

switch Cmyltea) [ 

^ ll lots of lines omitted here 
case kItemIsNeg: 
gIsHeg ” IgIsNeg: 

GetDialogIt^an(ioyDlalog, myltem. NULL. NULL, fctnyRect) i 
HoveToCmyRect.ieft 2, ntyRect.top + 17) i 
HacFraiaeRect (SimyRecr); 

Mac Ins etRoct (iiny Rect. 1. 1): 

Eras eRec t(SmyRe ct): 

MacInsetRect{SmyRect, -1, '1)t 

TextSlzeCkTextBigSlze): 
if CgIsNeg) 

DrawstringC"\p-"3: 
else 

Drawstring i 

Texts iz e (ItTeictRegSize) ; 
break; 

default: 

break: 

I 

) while ((myitem 1” kStdOkltemIndex) kh 

[myItern E= kStdCancellteffllndex)); 


AxS you can see, this code draws into the dialog box from 
within the Modal Dialog loop. That is to say, each time the 
user dicks in the rectangle of the kitemIsNeg dialog item, 
this code erase.s that rectangle and redraws the or 
symbol. This happens to work just fine on Macintosh 
computers, but it doesn’t work quite right on Windows 
computers. (The symixils draw okay when the user dicks 
in the item rectangle, but they are not redrawn if the 
dialog box is covered up and then uncovered.) Instead, 
we need to make sure %ve use the method recommended 
by inside Mactniosbr which is to dellne a user item 
caiibuckprocedure, as shown in Listing 6. 

Listing 6: Drawing a user item (revised version) 


Q'n C :_t) pilons Use rl t einProcediire 

PASCAL_RTN void QTTC_OptioTisOserItemProcedure 

(DiaiOgPtr theDlalog. Ehort theltem) 

( 

Handle myltemHandle “ NULL; 

Rect myRect: 

CantrolHandle myControi = NULL; 

if (theltem != kltemrsWeg] 
rettim: 

MacSetPorttG€tDialogPort(theDlalog)): 

GetDialogltein(theDlalog, thsltenk, NULL, NULL, £j!tyRect) : 
MoveTo(niyRect.left + 2. myRect.top + 17) r 
MacFrameRect (SonyRect); 

MacInset Rec t £ AmyRec t. 1 * 1); 

EraseRect£&myRect): 

MaclnsetRect(AmyRect. -I* -1); 

TextSizefkTextBigSlze)i 

if (glsHeg) 

DravStrliig(“\p *'): 
else 

Drawstring('■\P'1-"); 

TexrSlzeCkTextRagSlze)# 
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Then, before we display our dialog box, we install the 
callback procedure by calling GetDialogItem and 
SetDialogltem: 

gOptionsUfierltemProcUPP = 

NewUser11 emP roc(QTTC_OptionsUserIteniProcedure}; 
GetDialoglteaCTuyDialog, klteniIaHeg, &myKind, &myHandiep 
imyRect): 

SGtDialogItam{[nyDialogH kItemIsNegt myKind. 

(Handle)gOptionsUserltemProcUPP- imyRect); 


(In fact this has always been the recommended way to 
draw user items in dialog boxes, but you never know 
when shortcuts have been taken.) 

There is one final step we need to take here, which is to 
have die Dialog Manager call our user item callback 
prcx:edure whenever the u.ser clicks in the user item rectangle. 
We can do this by calling InvalRect or InvalWindowRect. Now 
the code for the kftemIsNeg case should look like this: 

case kItemIsNeg: 
glsNeg ” tglsNeg: 

GGtDialogltEiii{tnyDialogp myltem, NULL* NULL* fijEyRect); 

#if TARGET_API_MAC_CARBON 

InvalWlndo’wRGCt (GetDialDgWindow(niyDialog), &myRect) : 

#else 

InvalRect(imyRect3; 

DrawDla 1 og {myD ia 1 o g) r // farce a redraw (nece?ij{aiy an Windows) 

#endif 

break: 


Now look again at Figure 2. You'll notice that it 
contains a pop-up menu control that allows the user to 
select a font. When I was adding the font pop-up menu 
to QTTimeCode, T diligently followed Imide Macintosh^ 
according to which we can specify a resource type in the 
control reference constant field of a control resource and 
add the value popupUseResMenu (0x0004) to the control 
definition ID. In other words, I constructed the control 
resource shown in Figure 4. 


iCNTL m 128 from QmmeCoOe,qtrl 


BoufidsRect 

Voim 

Visible 


228 { 

194 

247 

379 

e 



#True O False 


nax 

40 


nin 

1000 


ProcIO 

1012 


RefCon 

1179882516 | 

Title 

FoRt: 




I've found dial* under Windows* we also need to call DrawDialog Figure 4: RcsEdit definiikm of a 

to get tile appropriate parts of the dialog box to redniw. menu coniroL 
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(Here, 1179602516 is 0x464F4E54, or TONT' in ASCIL) 
The Control Manager will add the names of all resources 
of the specified type to the pop-up menu when it creates 
that menu. 

Unfortunately, 1 couldiiT get this to work on 
Windows. Instead, 1 needed to programmatically add the 
names of the available fonts to the pop-up menu control, 
as shown in Listing 7: 

Listing 7: Adding font names to a pop-up menu 
control 


QTTC_Getn mcCodeOptio ns 

myControl “ QTTC_GetDIteiiiRect {myDlalog, 

kFontPopUpWenuGontrolH SmyRect): 
if [myControl != NULL) ( 

myMenu ™ MacGetKenii{kE'cnLtPopUpRGsID) : 
if {myMenu != NULL) ( 

#if ACGESSOR„CALLS_ARE_FUKCTIONS 
// insert the menu into the menu list 

MaclnsertHenuCmyMGnu. klnsertHlerarcMcalMemi) : 
SetControiFopupMenuHandleCmyControl, myHenu); 
SetControlPopupHennlD(myControl» kFontPopUpRGsID); 

#Gl3G 

PopnpPrivateData myPrivateData; 

// insen the menu into the menu list 

Mac Ins ertMetnittny Menu* klnsertHierarchicalMenu): 
rayPrivateDats, EnHandle ^ myMenu; 
myPrivateBata.mlD ” kFontPopUpfieBlD; 

(PopupPrivat eData)(* *(PopupPrivat eDa taHand1e) 

{'‘myControD .contrlData) ^ niyPrivateData ; 

#endif 

// clean out existing menu 

while (CountMenu11 ems(myMe nu}) 

DeleteMenUlteiiDCniyMenu, 1) ; 

// add in the available fonts 

Append Re sMenu(myHenu, FOUR_CHAR_CODE{'FONT'))■ 
SetControlMaximmn [myControl. CountMeniiltEma (myMenti)) ; 
SetControlValue{myCnntrcil* gFontIndex): 

I 

I 


It would have been nice if QTML had correctly 
interpreted the CDriginal control resource, but die workaround 
is straightforward and completely cross-platform. 

Working With Modeless Dialog Boxes 

As weVe seen, modal dialog boxes (that is, dialog 
boxes w^hose event handling is accomplished using the 
ModalDialog function) work well on Windows, with very 
minor adjustments to our existing Macintosh source code. 
Working with modeless dialog boxes requires a bit more 
work, how^ever. The main reason for this is that, because 
our Windows application is not driven by a Macintosh- 
style event loop, we cannot use the IsDialogEvent and 
DialogSelect functions to detect and handle events for 
modeless dialog boxes* Instead* need to install a 
callback function to handle Windows messages generated 
by the main message loop. 

Let's suppose that we want our application to display 
the modeless dialog box shown in Figure 5 (Macintosh 
version) and Figure 6 (Windows version)* 
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figure 5: A modeless dialog box (Macintosb) 



Figure 6: A modeless dialog box (Windows} 

This dialog box contains three radio buttons for 
dynamically setting the looping slate of the frontmcjsi 
movie window. In our Macintosh code, we can display 
the dialog box like this: 

gLoopDlg = GetNewDlalog(kLoopCLOGResID♦ NULL* 

(WindowPtr)-1): 

And then we can intercept events targeted for this dialog 
box in our main event loop, like this: 

Listing S: Handling events in a modeless dialog box 
(Macintosh) _ 

QTFnimc_Ma.in CvcnttXwp 

VaitNextEvent(everyEyeiit« ^myEvent, kWNEDefauItSIeep, NULL); 
if (laDialogEvent t ^inyEveiit) J 

if (DialogSelect(^myEventH &ntyDlaIog* toyItemHit]3 I 
if fmyDialog = gLoopDlg) 

QTXP_DaLoopDlalogEveiit(&myEvGiit, nryDialog* myltemlllt); 
continue: 

] 

ifere, we call IsDialogEvent to determine whether the 
event is targeted at a dialog box. Then we call 
DialogSelect to get the dialog pointer and the number of 
the item hit. Finally, we call the application function 
QTXP_DoLoopDialogEvent to handle the event. (We w'on't 
bother to consider QTXP_DoLoopDia[ogEvent here; it just 
sets the control values (>f the radio buttons as apprcjpriate 
and changes the looping mode of the frontmost movie.) 

On Window^s, as I’ve said, there is no event loop, so 
we can't call IsDiafogEvent and DialogSelect. Instead, w^e 
need to install a modeless dialog box callback procedure, 
by calling the SetModelessDialogCallbackProc function: 


gLoopElg = GetNewDialog(kLoopDLOGRGsID, NULL, 

(WindowPtr)-1): 

#if TARGET_OS_VIN32 

S etMod e1e s sDia1□gCa11ba ckPr q c( gLoopDlg, 

{QTModelGGECallbackUPP)QTXP_LooplrkgDlalogCallback): 
fcdif 

QTML calls a modeless dialog box callback procedure 
whenever it processes a message that’s targeted at an item 
in the modeless dialog box. QTML first translates that 
message into a Macintosh-style event, which it passes as 
a parameter to the callback procedure (along with the 
dialog pointer and the number of the affected dialog 
item). Our callback procedure, defined in Listing 9, is 
quite simple. It just calls the application function 
QTXP_DoLoopDialogEvent to handle the event. 

Listing 9: Handling events in a modeless dialog box 

(Win d ows) _ _ _ _ 

QTXP_Lr )pi n gOialogCa 11 back 

#if TARGET_0S_WIN32 

void QTXP_LoopingDialogCallback (EventRecord ’theEvent* 

DialogPtr tbeDialog, Dialogltemlndex theltemHi^} 

I 

if (theDialog NULL) 

QTXP„DoLoopOialogEvGnt(theEvent* theDialog, theltemHit); 

I 

■fendif 

Once wcVe added a mcKlclcss dialog box callback 
prcKedure in tliis way, the dialog box shown in Figure 6 will 
work as expecled on Windows. (You might be wondering 
why we didn't just install QTXP_ Do Loop Dialog Event as our 
modeless dialog box callback procedure, since aO 
QTXP_LoopingDialogCallback really does is call 
QTXP_DoLoopDialogEvent. The answer is that, in the future, 
our callback [procedures will need to lie more complicated; so 
Fve opted for illustmting the more general case here, even 
though it isn’t strictly necessiuy,) 

Handling Strings 

Let’s take a look at hnw^ we mighi need to adjust our 
handling of strings (that is, sequence.s of individual 
characters). Strings passed to Macinto.sh APIs are 
generally expected to be Pascal strings, which consist of 
a length byte followed by that number of characters. Most 
Macintosh C compilers recognize the ‘\p’ escape sequence 
for constructing Pascal strings. For instance, Listing 5 
contains this line: 

DrawStringP'\p+'') : 

The parameter to DrawString is a siring constant, which 
our compiler formats as a Pascal string. In memory, this 
.string occupies two bytes, having the value 0x0128. 
Similarly, the string hello, w^orkP occupies 13 bytes (12 
characters plus a length byte). Because the length of a 
Pascal siring is .specified by a single byte, a Pascal string 
can contain at most OxFF (that is, 255) characters. 
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By contrast, the C programining language supports C 
strings, which consist of some number of characters 
followed by a termination character (the byte 0x00, or ‘\09* 
There is no length byte in a C string, so C strings can be 
arbitrarily long. Many Macintosh programmers — myself 
included ~ prefer to work primarily with C strings; as a 
result, when we want to call a function like DrawString that 
requires a Pascal string, we need to convert the C string to 
a Pascal string. In the past, IVe used the function c2pstr, 
which converts its argument in place: 

char myStrlngl] = world*': 

DrawString(c2pstr(myString)); 

The C string ''hello, world” looks like this in memory: 
0x6SS56C6C6F2C2O776F726C640O 

After the call to c2pstr, that same block of memory looks 
like this: 

OX0C68656C6G6F2C2O776F726C64 

As you can see, the characters in the C string have been 
shifted to the right, and the length byte (here, 0x00 has 
been inserted before the first character; the byte formerly 
occupied by the termination character is now occupied by 
the last character in the string. 

To avoid this string conversion, we can use special 
glue functions that take C strings as parameters, rather 
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than Pascal strings. For instance, the file QuIckdrawText.h 
declares the function drawstring, which takes a C string: 

char myString[] = ’‘hello, world*': 

drawstring(myString ); 

So far, so good. But several problems arise when we 
try to make our string-handling code work under QTML 
and under Carbon. First of all, these glue functions are 
not supported under Carbon, so we need to restrict 
ourselves to those functions that work with Pascal strings. 
Further, the functions c2pstr and p2cstr are likewise not 
supported under Carbon. (Instead, Carbon supports 
several similar functions, c2pstrcpy and p2GStrcpy.) 

Another problem is that not all Windows compilers 
suppon the '\p’ escape sequence for creating Pascal strings. 
Microsoft Developer Studio Visual C/C++ versions 5 and 
earlier did support it, but that .support was dropped in 
version 6. In that case, the string "\phella, world” would be 
misinterpreted as the C string “phello, world”. To help 
prevent such unexpected results, QTML examines Pascal 
strings whose length byte is (that is 0x70 or 112) to see 
if they are really misgenerated C strings; if they are, it calls 
c2pstr to conven them in place to bona fide Pascal strings. 

ThLs is wonderful, unless our strings happen to be 
located in read-only memory (in which case having QTML 
call c2pstr on them would cause an access violation). The 
safest course of action is probably to avoid using the ‘\p' 
escape sequence entirely (so that Windows compilers 
don't ever get the chance to misinterpret it). Instead, well 
create ali strings as C strings and then convert them to 
Pascal strings whenever we need to pass them to a 
function that requires Pascal strings. 

Bui which functions shall we use to make this 
conversion? Early on in my efforts to port Macintosh code 
to Windows, I decided it was simplest ju.st to define my 
own functions for converting strings from one form into 
another. That way, we don’t need to won 7 about whether 
any functions have been deprecated by the move to 
Carbon, or QTML, or whatever. Listing 10 defines the 
function QTUtils^ConvertCToPascalString, which weVe 
used many times in this series of articles for converting C 
strings to Pascal strings. 

Listing 10: Converting a C string into a Pascal string 

QTlTiils_ConvenCToP^caLString 

StrlnaPtr QTUtils^ConvertCToPasealString, (char *theString) 

[ 

StringPtrmyString = malloc£min(strlen(theBtrlng} + 1, 

256}}; 

short inyindex = 0: 

while ({theString[myIndex! '\0‘) && [myIndex <255)) [ 

myStringlmylndex t 1] = theString[myIndex] : 
mylndex++: 
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myString[Oj = (unsigned char)EnyInde3^: 

return[myString)' 

I 

There’s no magic here: we just allocate a buffer large 
enough to hold the characters in the C string (up to a 
maximum 255 characters) and the length byte of the 
Pascal string, copy the characters from the existing C 
string into the new buffer, and then finish up by 
prepending the length byte. Listing 11 defines the 
QTUtils_ConvertPascalToCString function, which performs 
the reverse conversion. 

Listing 11: Converting a Pascal string into a C string 

QTIJ t il s_Con ve rtPascal'!bCJ S ir ing 

char *QTUtils_CDnvertPascalToCString (StringPtr tbeString) 
f 

char *niyStrin^ = inalloc(theString[0] + 1): 

short mylndex = 0: 

for (tnyindex ^ 0: mylndex < theString[0]; tnyIrLdex++) 
iiiyStrlna[inyIndexl “ tbeString [my Index + 1]: 

myString[theBtring[0]] = '\0‘: 

return(myString)j 

1 

Whenever we use Lhese functions in our code, we 
need to make sure to free the buffer allocated by malloc, 
by calling free once we’re done using the string. 

Let’s sum this up. Our preferred method for working 
with strings will be to create all strings as C strings. When 
we need a Pascal string, we’ll explicitly create a new 
Pascal string by calling QTUtils^ConvertCToPascalString. To 
illustrate, reconsider these lines frcnn Listing 5: 

if [gIsNeg) 

Dr 0 ¥String('*\p-"); 
else 

DravString(''\p+**): 

We’ll need to rewrite them now, like this' 

StringPtr mySign = NULL; 
if (gIsNeg) 

myEigrx “ QTUtils_ConvertCToPa£calStrlng: 
else 

mySign ^ QTUtils_CoiivertCToPascalStrlng['''+'^) ; 

Drawstring(raySign); 
free{mySign): 

Updating last month’s QTTimeCode sample code is left as 
an exercise for the reader. 

Converting Data Types 

Occasionally we need u> convert between similar 
Macintosh and Windows data types. One case that pops up 
often enough to warrant attention is the conversion 
between the Macintosh data type Reel and the Windows 
data type RECT. The fields of these structures have the 
same names, but in a Rect, the fields are of type short, while 


in a RECT they are of type long. (Also, for what it’s worth, 
the fields are not in the same order in these two structures.) 
QTML knows how to do this conversion, but it does not 
provide a public API for it; so 1 wrote the function 
QTFrame^ConvGrtMacToWinRect defined in Listing 12. 

Listing 12i Converting a Macintosh rectangle into a 
Windows rectangle 

QTFrame^Co n vertMacTo WinRect 

void QTFrame^ConvertilacToWinRect (Rect *theMacRect* 

RECT * theWinRect) 

( 

theWinRect->top = (long)thaMacRect->top: 
theWinRect‘>left = (long)theHacRect->left; 
theWlnRect'>bottDm “ (long)theHacRect-^bottom; 
theWirYRect->right ^ (long)theMacRect->righT; 

We’ve bumped into this function previously (in “Word Is Out”, 
Maclech, November 2000) but haven’t discussed it explicitly. 
It’s really rather simple, of course. (So much so that I'll leave 
the companion function QTFrame_ConvertWinToMacRect as an 
easy exercise for tlie reader.) 

QTML does provide some useful functions for 
converting other kinds of stmetures. For instance, we can 
convert between Macintosh regions (of type MacRegion) 
and Windows regions (of type Region) by calling the 
MacRegionToNativeRegion and NativeRegionToMacRegion 
functions. See the “QuickTime For Windows Programmers” 
document referenced at the end of this article for exact 
details on these and other conversion functions. 

Handling Text 

Dialog boxes, both modal and modeless alike, often 
contain fields where the user can enter and edit text. The 
dialog boxes shown in Figures 2 and 3 use the Control 
Manager’s edit-text control. Some Macintosh applications 
use TextEdit for more complicated text support, QTML 
does not support TextEdit, If you need simple text entry 
and editing services, use the edit-text control (in a Mac- 
style dialog box) or use the Windows native edit control (in 
a Windows window). If you need more complicated text- 
editing services, you 11 have to do a bit of programming. 

Carbon 

Unlike QTML, Carbon is a porting layer. In paiticular, 
Carbon is a set of programming interfaces and a run-time 
library that together define a subset of Macintosh APIs that 
are supported both on “classic” Mac operating systems and 
on die new Mac OS X. By writing our code to conform to Che 
Carbon standard, we can ensure that our compiled 
applications will run on both Mac platforms. 

In general, it’s easier to port existing QuickTime code 
to Carbon than it is to port it to QTML. There are just a 
few issues we need to pay attention to when reworking 
some existing Mac code to run under Carbon (that is, 
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when Carbonizing our application). First, we need to 
make sure that ail the OS and Toolbox functions we call 
are pan of the Carbon standard. This is because some 
existing functions have been dropped (usually in favor of 
better technologies). Second, we need to make sure that 
we use accessor functions whenever necessary. This is 
because many of the data structures that hitherto were 
public are now opaque; we cannot directly read or write 
the data in their fields. 

At times Carbon and QTML seems to be working at 
cross-purposes, but it turns out that it's fairly easy to 
support both Carbon and Windows with a single set of 
source code files. In this section, I want to focus on the 
kinds of changes we need to make to our QuickTime- 
savvy code to get it to run on Carbon, w^hile maintaining 
our Window^s compatibility. (General information on 
porting to Carbon can be found elsew^here.) 

Accessing Fields of Data Structures 

Under Carbon, many of the key data structures used 
by the OS and Toolbox managers have been privatized 
(made opaque). For instance, in the not-too-distam past, 
the standard way of getting the menu ID of the menu 
associated with the menu handle myMenu was like this: 

mylD = {*^myMenu)*menuID: 

Nowadays, when we're targeting Carbon, we must instead 
use the accessor function GetMenulD, like this; 

my ID = GetMenuIDl rnyMetiu} ; 

It turns out, how^ever, that GetMenulD (like most of 
the new accessor functions) is not supported by QTML. So 
we might conditionalize our code, like this: 

#if ACCESS0R_CALLS_ARE_EUNCTIONS 
inylD — GetMenulD (itiyMenu) : 

mylD = ( * *iiiyMenii) . memilD; 

(/end if 

Alternatively, we could just stick the following lines 
somewhere in one of our project'.s header files: 

//if IACCESSOR_CALLS_ARE„FUNCTIONS 
//define GetMenulD{tnHdl) {* *iiiHdl) .menuID 
//endlf 

In this case, we can call GetMenulD without wonydng 
wdiether we're building a Carbon application or not. 

Which of these (or still other) options you adopt is 
largely a matter of taste, I suppose. Personally, 1 generally 
opt for the former approach. Partly that's because it’s not 
always so easy to concoct a suitable #define. Ideally, 
however, the Apple-supplied header files should contain 
those defines, or else QTML should implement the 
accessor functions. 
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Replacing Unsupported Tunctions 

The really troubling problem in writing Carbon- and 
QTML-eompatible code concerns Mac OS and Tcx>Ibox 
functions tliat have been dropped entirely from Carbon. A 
gcxKl case in point is die ICM function StandardGetFilePreview. 
Not too terribly long ago, we used StandardGetFilePreview in 
both Mac and Windows code to elicit fUes from the user. 
StandardGetFilePreview relies on the services of the Standard 
File Package, which is not supported under Qirbon. So we 
need to rework our file-opening and -saving code to use the 
Navigation Services APIs, 

In this case* 1 decided to create wrapper functions diat 
internally call either the Standard File Package or Navigation 
Services, depending on our target runtime envircjnment. For 
instance, to elicit a file from the user, I wrote the 
QTFranne_GetOneFlleWfthPreview function, show^n in Listing 
13 . It may be a bit lengthy, but it does the trick. 

Listing 13: Eliciting a file from the user 

QTFrame^G ctOncFik Wi t h Pre V ic w 


Version 

Control 

the 

Macintosh 

Way 


Is 




The Version 
Control Tool for 
CodeWarrior 
Developers 




Q 


OSErr QTFraine_GetOn€FileVithPFeview (short theUmoTypes* 
QTFrajneTypeListFt]: theTypeLlfit, FSSpecPtr 
theFSSpeePtr, 

void *theFilterProc) 

[ 

#if TARGET„0S^WIN32 

StandardFileRepiy myReply: 

#endif 

Hf TARGET_DS_MAC 

HavReplyReco rd myReply: 

NavDlaloaOptiona myDialogOptions: 

NavTypeLiGtHandlE myOpenList = NULL: 

NavKventUPP myEventUPP = 

NewNavEvantProc{QTFtame_HandlGNavEvetit}: 

#endif 

OSErr myErt ^ noErr: 

if (theFSSpecPtr == NULL) 
return (parataErr): 

// deactivate an>^ thmanost movie window 

QTFraine_ActivateContr oiler (QTFraine_GetFrontMovieWindow (), 

false): 


#if TARGBT_0S_VIN32 
// prompt the user for a file 

StandatdGetFilePrevievC £FileFilterUFP)theFilterProe, 

theNimTypes. (ConstSFiypeLiatPtr)theTypeLlat. &myReply): 
if (lmyRoply,BfGood) 

return(userCaneeledErr): 

// make an FSSpcc record 

myErr ^ FSHakeFSSpec£myReply.sfFile.vRefNura, 

rayReply.sfFile.parlL. rayReply.sfFile.nanie. theFSEpeePtr): 
#endif 

#lf TARGET„OS_MAC 

// ihc options for the dialog box 

NavGetLefaultUialogOptions (SmyDlalcigOptions): 
myDlalogOptions.dialogOptioTiFlags -= kNavNoTypePopup: 
layDialogOptlans. dialogOptlotiFlags '= 

kNavAllowMultipleFiles; 

BlockMoveDat a{gAppNaine. myDialogOptions.clientName. 
gAppName[O] + 1); 

// create a handle to an open'resource 

myOpenList “ (NavTypeListKaTidlE}QTFra]iie_CrEateOpenllandle( 
kApplleationSlgnature. theNuraTypes, theTypeList): 
if (myOpenList != NULL) 

HLockC (Handie)iiyGpeiiList): 
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U prompt the user for a hie 

rayErr - NavGetFile(KlILL. &myReply. ficmyDialogOpticins ♦ 

myEventUPE, MULL. (NavOhjectFiltertJPP)tbeFilterProc, 
myOpenLlst. NULL): 

if (CmyErr = noErr) && ntyReply.validRecord) I 
AEKeywo rd myKeywo rd; 

DeacType myActtialType: 

Size myActualSize = 0: 

// get the FSSpec for the selected file 
if CtheFSSpecPtr 1= NULL] 

ntyErr " AEGetNthPtr(fit(inyReply,selection) H 1* typeFSS, 
SmyKeyword. imyActualType > theFSSpecPtr, 
Eizeof[FSSpec). SmyActualSlze); 

NavDiaposeReply(SmyReply); 


if (myOpenList E= NULL] [ 

HUnlock((Handle)myOpenLifit): 
DisposeHandle { CHandle)myOpenList); 
t 

DisposeNavEventUPP(myEventUPP); 
#endif 

teturn(myErr): 

1 


Working with Universal Procedure Pointers 

There is one set of unsiipponed functions that is 
relatively easy to deal with, namely the three functions 
NewRoutineOescrlptor, DisposeRoutineDescrlptor and 
CallUntversalProc. On ‘"classic” Macintosh systems, a 
universal procedure pointer (UFP) is a pointer to a 
routine descriptor, which is a structure tliat occupies 
memory (and hence must be allocated and disposed 
oD. Under Carbon, the UPP data type is opaque, and 
might or might not require memory allocation. So we 
need to use a new creation and deletion function for 
each specific type of UPP we want to use. For instance, 
in Listing 13, we create a UPP for a Navigation Services 
event procedure by calling NewNavEventProc. To 
dispose of this UPP, we call DisposeNavEventUPP. 
Similarly, we can create a UPP for a modal clialog event 
filter by calling NewModalFilterProc. To dispose of this 
UPP, we call DisposeModalFilterUPP. If we ever needed 
to call this procedure ourselves, we would use the 
function InvokeModalFilterUPP. 

The good news here is that the header files for 
Macintosh APIs provide definitions of these new UPP 
functions for non-Carbon targets. For instance, the 
header file Dialogs.h contains scjme lines like this; 

//if OPAQUE„UPP_TYPES 

EXTERN_API{vold) DisposeModalFilterUPP 

(MadalFilterUPP UBerUPP); 

//else 

//definE DlsposeMcKialFl IterUPP [userUPP) 

DisposeRoutineDeecriptor(userUPP) 

/fend if 


This means that we can revise our code to use (for 
instance) DisposeModalFilterUPP and the resulting 
source code will compile and run on Windows, classic 
Macintosh, and Mac OS X. 

Conclusion 

The QuickTime Media Layer is a rock-solid 
implementation of key parts of the Macintosh 
Operating System and the Macintosh User Interface 
Toolbox for Windows computers. WeVe considered a 
number of changes that we might need to make to our 
existing QuickTime code to get it working on 
Windows. The changes are, all things considered, 
relatively straightforward. We occasionally need to byte 
swap data read from or written to a file. We need to 
ferret out the Mac APIs that have the same names on 
Mac and Windows and rename the Mac versions. We 
need to explicitly open our application's resource fork 
on Windows if we use any Mac-style resources. And 
we need to in.stall a callback procedure if we want to 
work with modeless dialog boxes on Windows. 
Otherwise, things work pretty much the same on both 
platforms. QTML is not a porting layer, but it is 
amazingly good at supporting a large set of Mac APIs, 
'fhere is, unfortunately, no definitive documentadon 
on which functions are available and which are not. 
My advice is to experiment; if a Mac function compiles, 
links, and runs on Windows, that's great. 
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SILICON VALLEY, October 16-17 

start Lip startups 

Attention. Join Garoge.corn's twodoy Bootcamp for S^or^Jps. Leorn the iundomentols of taking yoyr company:from startup to IFO Heor imm the high tech industry's 
top investors, experts, and entrepreneurs. Gain involuabb information about roising capital building a buzz, hiring top talent and bunching your product. At ease. 
LOG ON TO WWW,G ARAGE.COM/BOOTC AMP TO LEARN MORE B. REGISTER TODAY, 


WASHINGTON DC, November 15-16 
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San Francisco, CA 

January 9 -12,2001 
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Worfd-Class Exposition! 

Macworld Conference & Expo/ 

San Francisco 2001 is a 
One-Stop-Shop offering discounts 
not found anywhere else! 

• Featuring more than 5D0 
exhibiting companies 

• Thousands of new products, 
software and services 

• Hands-on demonstrations 

• Test-drive new technoiogies 
« Awards and competitions 

• Prizes, drawings, giveaways 

Speciai interest 
Beuievatd 

Macworld Conference & Expo offers 
so much for every Mac user! 

Check out the Special Interest 
Boulevard while you are exploring the 
exhibit floor to find and compare hot 
new products for your particular needs. 
Popular areas include; 

• Digital Media 


\, 


\ 


Join your friends 

and colieagues in the Mac community 
at The Largest !T eueot 
on the West Coast! 




Cutting-Edge 
Educationai Programs! 

Conference sessions for the 
New, Beginning, Intermediate and 
Advanced users! 

JWeeiiwrfitiffrv features technically In-depth 
presentations and issues-oriented discus¬ 
sions about professional applications of 
Macintosh technology. The Pro conference 
offers the most sophisticated training 
available on Mac networking, digital video, 
art director/creative management practices, 
and Mac systems administrations for 
large organ izafions. 

AbemufitUMrs continues to be one of 
the best educational values anywhere. 

The Users conference features industry 
experts offering skill development on 
the most popular Mac-related tools and 
professional development courses 
for users who rely on Apple technology 
to gain a competitive advantage. 




./ 






• Smali Business 

• Sci-Tech 

• Education/Assistive Technology 

• 3D 

• Edutainment 

Be sure to visit www.macwerldexpo.cem 
for exciting additions! 


MaeB^lonlags- San Francisco debut! 

After great success this July in New York, 
MacBeginnings will make it’s debut 
in San Francisco! These high-energy, 
informative sessions will provide 
first-time attendees, new and beginning 
Mac users a starting point to enter 
the Mac community. MacBeginnings are 
free and open to AIL registered Macworld 
Conference & Expo attendees! 


Macworld 

Conferenuo & Expo. 
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Getting Started with Mac OS X 


T he first and more important tiling you should know about 

Mac OS X is that it is coming soon! A public beta of Mac OS X 
was released in September and Apple will deliver the first 
commercial release of Mac OS X in early 200L For overall 
information about Mac OS X and developers, please visit: 
http: //developer, apple, com/macosx/ 

This article presents you with many options for Mat OS X 
development. Ultimately, however you will need to make your own 
choices, factoring in current code base, time to market concerns, 
and platforms to be supported. 


The Apple Developer Connection 

is pleased to present a new series of articles 
specifically designed to help facilitate your 
Mac OS X development. In the upcoming 
months, Apple’s Technology Managers will 
present articles covering topics such as 
the Cocoa and Carbon APIs, Apple’s new 
development tools, I/O Kit, Quartz, Aqua, 
and more. 

These articles will present an overview of 
key Mac OS X technologies with pointers to 
online resources from Apple that provide 
more in-depth information. Accompanying the 
feature articles will be sidebars and helper 
articles to help you more effectively navigate 
Apple’s technical documentation and to teach 
you shortcuts and tips that will improve your 
code and accelerate your development. 

Whether you’ve already investigated 
moving your products to Mac OS X or not, 
these articles should help you get started and 
resolve open issues. 


Forks in the Road 

Before you begin, you will need to know 
the answers to the following: 

• What platforms will you support - 
Mac OS 9, Mac OS X, Unix, Windows? 

• Are you w^riting an application, a 
driver, creating a system extension, etc? 

• Do you have a preexisting code-base? 

How large is it? Is it in need of an overhaul? 

Your answers to diese questions will help you choose the most 
effective development path, and ultimately deliver a better Mac OS X 
product. 

Let’s begin with the most common scenario; you're a Mac OS 
application developer who already has code based on Mac OS 9 or 
earlier. There are two most likely paths for you. You may use Carbon, 
the modern set of APIs founded on the traditional Mac OS APIs, or 
you may use Cocoa, the newer Mac OS X-only object-oriented APIs. 

Carbon 

'rhe best route for your product depends primarily on your time to 
market and platform needs. Vtdiile Cocoa allow^s you to build your 
application more efficiently and quickly, you may not have the time 
to rewrite your application in a new framew^ork. If this is the case, 
Carbon may be your best route. You can find out how to get started 
carbonmng your application at: 

http://developer, apple. com/tecbpuhs/macosx/Carbon/carhon. btml 
Cocoa 

If you have the time to redesign your application to take advantage 
of a modern object-oriented framew^ork and would like to produce a 
Mac OS X-only application, the rapid development tools and robust 
Cocoa framework will let you create a superior Mac OS X product. 

If you currendy have very litde code written or none at all, and 
you are interested in creating a Mac 0^S X-only solution, then you 
should investigate Cocoa, It’s definitely worth investing the shon 
amount of time it takes to come up to speed. For information on 
Cocoa development, visit: 

http: /Ideveloper. apple. com/techpuhs/macosx/Cocoa/ 

Cocoa Topics, btml 


7fm Holmes is Manager of the JUac OS Technology Management group in Apple Worldwide Developer Relations. He's In his 6ib year at Apple, 
having spent the past four in the role of Mac OS Evangelist for Mac OS 7. 6 through Mac OS 9, 71m has been in the Macintosh industry for over a 
decade, dating hack to his imrk at BMUG, and has beett an Apple user for over 23 years. 
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Driver Development 

On the hardware side, the TO Kit for Mac OS X provides Mac d^elopers 
with a new^j much easier w^y to create drivers. Remember, however, 
that w hat you may have once thought of as a driver under Mac OS 9 
may not be considered a driver under Mac OS X. You can find out all 
you need to know^ on this topic under the Kernel hiding at: 
bttp:l/developet: apple, com/tecbpuhs/macosx/macosx. btml 

System Extensions 

Finally, if you are considering extending or customi 2 ing the 
operating system, there are numerous ways to do so. In order to 
create a more stable platform, some changes were made to Mac OS 
X that make the methods you may have used for Mac OS 9 no 
longer applicable. For more information about this topic, please 
see: 

http:!/developer, apple. com/tecbnotes/tn/tn2003. hlml 

New to the Mac? 

Because Mac OS X combines support for a variety of technologies 
beyond those typically associated with the Mac, it presents non-Mac 
developers with some interesting new opportunities as well 

Java Developers 

Mac OS X has an incredible implementation of Java 2, providing you 
with a consumer desktop platform for your Java applicatioas and 
applets. If you wish to create a Windows/Mac OS compatible solution, 
Java very w^ell may be your best route. WhaFs more, via JFC/^wing, 
you can get Mac OS X's Aqua interface for free. You'll find 
information and documentation on Ja^^ dcA'Clopmeni on Mac OS X 
at: 

bnpilldeveloper.appie.comltecbpubsljavaljava.btml 
UNIX Developers 

If you already have a UNIX code base, Mac OS X presents a great 
opportunity for you. You can quite easily move your application to 
Mac OS X by taking advantage of the FreeBSD 4.4 APIs that Mac OS 
X is based upon. If you wish to quickly get your product up and 
running on Mac OS, simply pon your application to these APIs. 
However, if you are interested in attracting current Macintosh users, 
you should move the engine of your product over to Mac OS X, and 
write a Cocoa GUI that wall take advantage of Mac OS X’s features. 
To accompiish this, see the Cocoa documentation mentioned above 
and the BSD documentation below: 
hup: a WWW. unix~sy^ems. orgionline. btmi 
hnp./jwww. netbsd. org 
hUp://www.Jreehsdorg 

XWindovi/s Developers 

If you have an X^S'indow's product, then you’re in luck as Tenon’s 


XToois allow’S an XWindows solution to run unmodified, while still 
taking advantage of some of the native Aqua features of Mac OS X. 
For information on Tenon’s product, visit: 
hup: //WWW. tenon. com/products/xtools/pre~release_heta/ 

Until Next Time 

Fach of these paths to Mac OS X has alternatives, pros and cons, 
and each may fit one developer's needs better than another’s. Once 
you have fijlly investigated your options and decided wliich path is 
right for you, it’s time to get to work. And yes, there is w'ork to be 
done, but that is where we can help you succeed. 

We'll be covering more specific technologies in the upcoming 
articles. In the meantime, we welcome your suggestions on how to 
make how to make these articles more useful for you. Feel free to 
send email to me, Tim Holmes, at < shortstop@apple.com > with 
your comments. 


Discounts on 
Mac OS X Migration 

Bring Your Apps to Mac OS X 

With Mac OS X Public Beta here, and the 
commercial release just over the horizon, Mac 
developers everywhere have a huge need for 
Carbon and Cocoa application porting, Aqua 
user interface implementation, and driver 
development services. Several high-quality 
software engineering firms, in association with 
the Apple Developer Connection, are offering 
these services at very attractive discounts to all 
ADC Select and Premier members. 
http://developer.apple.com/nikt/ 
macosxmigration.html 

End-User Tech Support 

We all know how expensive and time consuming 
it is to set up and maintain a comprehensive 
customer tech support department. To support 
developers in their migration to Mac CS X, 
877MacTank has designed an exclusive and 
affordable tech support staffing program for ADC 
Premier and Select members. 
http://developer.appie.com/mkt/mactank.html 







New Mac OS X 
Related Releases 


Worldwide Public Beta Developer Tools 

Developers may download the Mac OS X Worldwide Public Beta 
Developer Tools version from the Download Software area of the 
ADC Member Site, This download must be used with the Mac OS X 
Public Beta User CD (the 74anguage version), available from the 
Apple Store. This software set supports 7 languages including 
Spanish, Italian, & Japanese. ADC Select and Premier members were 
sent this CD set in October. 
bttpJIconnectMpple, com! 

Latest CarbonLib SDK 

The CarbonLib SDK provides all the files needed to begin Carbon 
development. ADC Members may download the latest prerelease 
version from the Download Software area of the ADC Member Site, 
http: iicon tied apple, com! 

Apple Memory Guide November 2000 

The Apple Memor)^ Guide (AMG) contains memory upgrade 
information for Macintosh computers and LaserWriter printers. 
bttpiUasu. info, apple.comiswupdates. nsJlartnumlnlOOB4l 

Automatic Update Software 1-2 

Automatic Update Software 12 provides enhancements to make 
software updates over the Internet faster and more efficient. 
bttpiUasu. infoMpple. com/swupdates, nsfiartnuminl / 862! 

Developer Documentation 

The following new and updated documentation is available to help 
you on your way to successful Mac OS X application and peripheral 
development at: 

bitp; a developer, apple, comltecbpu bsj 

• Carbon Specification 

• Font Management for Carbon and Mac OS 9 

• Guidelines for Writing Help Tags 

• Adopting the Aqua Interface 


• TNI 173 - Understanding Open Transport Asset Tracking 

• TNI 104 * * Interrupt-Safe Routines 

• TN2007' 'Vhe CGDirectDisplay API 


• TN2008 - The CGDirectPalette API 

• Q&A DV45 - Coordinating Deferred Tasks and Secondary 
Interrupts 

• Q&A QD61 - GetPortBitMapForCopyBits 

• Q&A QD62 - CalcCMask and SeedCFill in Carbon 

• Q&A QD63 - Finding the Bit Depth of a Carbon Printing Manager 
Graphics Context 

• Q&A QD64 - ATSUl and MLTE Printing 

• Q&A QD65 - QDFlushPortBuffer 

• Q&A QD6iS - Replacing OpenPort in Carbon 


Did You Know? 

Developer Help Center 

When it comes to programming for Mac OS X, 
do you feel like an explorer on the shore of a 
vast new continent? Don’t worry, there are 
“charts” to guide you—^the developer 
documentation you get when you install the 
Developer package. 

You can access this information through the 
Developer Help Center, a section of the Help 
Viewer application. To get to it, first open the 
(user) Help Center by choosing Mac Help from 
the Finder menu. Then click the “Developer Help 
Center” link at the bottom of the page. 

The Developer Help Center works just like a 
Web browser. You can either navigate through 
the sets of documentation by clicking links or 
you can search for specific information. 
Searching is as simple as typing text (phrases, 
words, or API symbols) in the field at the top of 
the application and clicking the Ask button. The 
search engine returns a weighted list of “hits” 
(links) you can browse through. The Developer 
Help Center also lets you focus your searches 
on the set of documentation you are interested 
in. Thus a search when you are perusing 
Carbon documentation confines the results to 
Carbon. If the results yield nothing of interest, 
you can easily expand the search to the 
complete set of documentation. 

There are some known bugs in the Public 
Beta version of Help Viewer; see the release 
notes for details. 
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Upcoming Seminars 
and Events 

For more infonnadon on Apple developer events 
please visit the Developer Events page at 
bttpiUdeveloper. apple.cvmleventsi 

Training and Seminars 

• Apple V^ebObjects Programming Classes 

Five-day programming courses from Apple iServices Group 
are avaitabie worldwide. Check out their schedule at 
btlpJfummK apple, comliservicesitechnicaltrain ing/sdiedule. btml 

• Programming WebObjects 1 afid 2, and 
Programming with Cocoa 

Taught by Aaron Hillegass at the Big Nerd Ranch in Asheville, NC 
Five-day classes for programmers on developing web-based 
applications. 

http', IIWWW. bignerdramh. com! when, btm i 

Developer-Related Conferences 

• MAO?fORLD Expo San Francisco 2001 
January 942, 2001 

Macworld Conference & Expo provides you with the opportunity 
to introduce both business professionals and consumers to your 
company and products. Special MAOTORLD Conference & Expo 
exhibitor packages including hardware discounts are available for 
ADC Premier and Select members. 
bttpiUdeveloper.apple. comlmktlmwsf200Lbtmi 

• MACWORLD Expo Toi^o 2001 

Februar)" 22- 24, 2001 at Makuhari Messe, Japan 
MACWORLD Conference & Expo Tokyo provides you with 
the ideal venue to introduce your company and products to 
over 200,000 eager attendees. Special exhibitor packages 
and hardware discounts for ADC Premier and Select members 
are available. 

http://dei}elopenapple,cam/mkt/mwtokyo200Lhtmi 


ADC Programs 
and Mac OS X 

T he Apple Developer Connection (ADC) 
helps Macintosh developers build, test, 
market, and distribute software and 
hardware products for Mac OS X. ADC Program 
members receive advance copies of Mac OS X 
software and development tools such as Project 
Builder and Interface Builder directly from Apple. 

Programs range in price from $0 to $3500 and 
are available worldwide. Certain levels of 
membership entitle developers to benefits such 
as pre-release software seeds, Apple hardware 
discounts, technical support. ADC Television, 
and passes to the Worldwide Developers 
Conference. Special ADC Member Discounts, 
included with membership, may be used for 
third-party services including Mac OS X 
migration. Aqua and Cocoa integration, quality 
assurance, application porting, and more. In 
addition, members receive discounts on 
developer products such as WebObjects and the 
WWDC Conference Sessions on DVD. 

And when your Mac OS X product is ready to 
ship, ADC helps spread the word. Apple’s 
Macintosh Products Guide highlights developer 
products that are “Built for Mac OS X” or 
“Classic Compatible”. If you offer developer 
tools or services, we'll also list your products in 
the weekly ADC News. 

For details on program membership, visit: 
http://developer.apple.com/membership/ 







PROGRAMMER'S 

CHALLENGE 


By Bob Boonstra, Westford, MA 


Tetris 

When George Warner first suggested that 1 base a 
Challenge on Tetris, I was skeptical. I hadn't played Tetris in 
a long time, and my recollection was that Tetris is a game not 
only of strategy, but of manual dexterity as wtIL After some 
email conversation, however, 1 think weVe found a w'ay to 
formulate Tetris info a meaningful Challenge. 

You remember how Tetris is played, right? The game is 
played on a board sized perhaps 10 cells wide and 20 cells 
high into which pieces of varying sizes are dropped. The 
player is able to move the pieces left or right as they drop, 
or to rotate them clockwise or counter-clockwise, or to drop 
them to the bottom of the board. The player accumulates 
points as each piece is positioned into its final location. As 
one or more row.s become completely filled, those rows are 
removed, the other rows are .shifted down, and more points 
are accumulated. As rcws are deleted, the game progresses to 
higher and higher levels where the pieces drop faster and 
faster The game continues until there is no room for the next 
piece to drop into the board. 

In this month's Challenge version of Tetris, the board 
size is generalized to something potentially larger than 10x20, 
the game speed remains constant, and the game continues 
until a specified time limit expires. You can make one move 
of the current game piece, a translation or a rotation, for each 
tick of the game clock. You can take as long as you like to 
figure out the best juove, but every microsecond you use to 
calculate your move subtracts from the time limit and reduces 
your opportunity to score additional points. So you need to 
plan your moves both carefully and quickly. 

The prototype for the code you should WTite is: 

typedef char Piece[7] [7]: 

r aPlecefrow|[cotl is 1 if aPiece occupies cell (row,col), 0 otherwise V 
typedef char Board[256] l256]; 

/* :ilioard[row|fccjl| is -1 If cell (row,col) is empty tjtlierwise It U the Piece index 7 
/* row^ 0 is the top row, col 0 is the leftmost column 7 


typedef enuni I 
kNoKove^O. 

kHoveLeft, kMoveRight. 
kBrop, 

kRotateCIockvise, 
kRotateCounteeClockwise 
\ MoveType: 


r allow piece to fall normally 7 
/* move piece left/right one column 7 
r drop piece t(? bottom of board 7 
r rotate piece ckickwise 9t) deforces 7 
r rotate piece counterclockwise 90 degrees 7 


void InitTetria( 
isbort boardWidth, 
shart haardHeight, 
short fiumPicceTypES. 
const Piece gaiiiePieces [] , 
long tirneToPlay 

}: 


r width of bijaid in ceIJs 7 
r height of board in ceIJs 7 
r number of types of pieces 7 
r pieces to play V 
f* game time, in millLscconds V 


MoveType /* move active piece 7 Tetris { 
const Board gameBoard. 

r current state of the game board, 
bottom row is IboardHeight-llrief: column is [0] 7 
short actlvePieceTypelndex, /* index Into gamePieces of active piece 7 

short nextPieceTypelndex, t hidex into gamePieces of next piece V 

long p 0 int sE a rned, /" nu mber trf points earned th us far 7 

long timeToGo /* time remaining, in milliseconds 7 

): 

void TerniTetris(void): 

The Tetris Challenge will work like this. Your InilTelris 
routine will be called first, to allow you to set up the problem 
based on the board configuration and the Piece shapes to be 
used in the problem. Next, your Tetris routine will be called 
multiple times, allowing you to manipulate the falling Tetris 
pieces, with the objective of aceumulating as many points as 
possible. Your Tetris routine will continue to be called until 
the specified timeToPluy has expired, or until no more Pieces 
can be placed on the board. Then your TermTetrls routine will 
be called, allowing you to deallocate any dynamically 
allocated storage, 

InitTetris wuli be provided with the width (boardWidth) 
and height (boardHeight) of the game Board, It will also be 
given the numPieceTypes gamePieces to be used in the game, 
and the length of the game {timeloPlay) in milliseconds. 

Each call to Tetris gives you the current state of the 
gameBoard; you should determine what you want to do with 
the active game Piece and return the corresponding 
MoveType. The test code will attempt to translate or rotate the 
active game Piece according lo tlie MoveType you specify 
prior to dropping the Piece down one row. If the Piece 
cannot be moved or rotated as you request, the Piece will 
simply drop dowm one row^ Wlien the active Piece drops as 
far as it can, it wall remain the active piece for one more 
game cycle, so that you can move it left or right by one 
position should you so choose. The Tetris parameters also 
provide you with the type of the next piece to be played 
(nextPieceTypeIndex), the pointsEarned so far, and the 
timeToGo still remaining in the game. 

The gameBoard will contain the value -1 in each empty 
cel!, and the index of the Piece occupying that cell for 
nonempty cells. Game Piece shapes are .specified in a 7x7 
array, with a I indicating that the corresponding cell is 
occupied. Pieces rotations occur about the central cell in that 
array. When Tetris is called wdth a new^ active game Piece, the 
Piece will be positioned just above the gameBoard, with the 
bottom row of the Piece due to appear on the gameBoard the 
next time Tetris is called. 

The winner will be the solution that scores the most 
Tetris points within the specified timeToPlay. You score 1 
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Making the Move 


point for each row that a Piece falls when it is dropped. 
When you eliminate a row, you earn 100 points. If multiple 
rows are completed at the same time, you win additional 
points: the second row completed by dropping a block is 
worth 200 points, the third 300 points, and the fourth 400 
points, ff you should eliminate all blocks on the board, you 
earn an additional 1000 points. 

The Challenge pri^e will be divided between the overall 
winner and the best scoring entty^ from a contestant that has 
not won the Challenge recently. If yr)Li have wanted to 
compete in the Challenge, but have been discouraged from 
doing so, perhaps this is your chance at some recognition 
and a share of the Challenge prize, 

This will be a native PowerPC Challenge, using the 
CodeWarrior Pro 6 environment. Solutions may be coded in 
C, C++, or Pascal. You can also provide a solution in Java, 
provided you also provide a test driver equivalent to the C 
code provided on the web for this problem. 

Three Months Ago Wincner 

Congratulations to Ernst Munter (Kanata, OntaHo) for 

another Programmer’s Challenge victory. Ernst submitted the 
winning entry to the October *^Which Bills Did They Pay” 
Challenge. This Challenge required contestants to sort out a 
set of invoices and a set of payments, matching payments to 
invoices. The solutions had to deal with payments that 
settled multiple invoices and partial payments of an Invoice. 
Scoring was based on minimizing a iate-dollar-days” value 
that was the product of the amount of the invoice (or part of 
an invoice) times the number of days the amount went 
unpaid, thus encouraging the solution to apply payments to 
the oldest applicable invoice. 

Ernst beat out the second-place entry by new contestant 
Sue Flowers. Sue’s solution generated the same late-dollar- 
days value that Ernst’s entry" generated, but required 
significantly more execution time to do so. In several of the 
larger test cases, Sue's entry generated the same bill 
reconciliation log as ErnsEs entr>^ did, although this was not 
true in all cases. Besides Ernst’s and Sue’s entries, two 
additional entries for this Challenge were submitted, but 
neither solved the test cases correctly. 

As always, Ernst’s code is well commented. His entry 
makes two passes through the payment list, the first time 
looking for either a perfect match with a single invoice or a 
perfect match with multiple invoices. Ernst's Combine! nvoices 
routine uses a stack-based technique to find the combination 
of invoices that exactly matches the payment amount. Although 
I didn’t specifically analyze the performance of the individual 
routines in Ernst’s code, I believe that the Combine! nvoices 
routine is key to the performance Ernst achieved. In the second 
pass, his code looks for the "^best” possible partial payment 
match, where ‘^besf is defined as the invoice with the invoiced 
amount closest to the payment amount. Finally, the code 
makes a third pass through any remaining unpaid invoices to 
calculate the late-dollar-days statistic. 
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With MjCjiHij Z just over the lMjAilll^ . 

Mac everywhere have a 

major need for CAR BOM and 
application porting, user interface 

implementation, and |j|£|i||( development 
services. Toward that end, several 
high-quality engineering 

firms, in association with the PIPPLI 
l][UELQP[R [QNWCCTiOti. are offering these 
services at very aHraoHiM discounts 
to all Select and Premier members. 


TKe following pages 
are those vendors that 
are part of the Mae OS x 
Porting & Development Showcase. 










Red Rock Software specializes in the Macintosh software devel 
opment. Red Rock Software's team of senior engineers aver¬ 
ages over 10 years of development experience on the 
Macintosh platform. Our expertise and experience has gained 
us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 

If you are looking to get your product compatible with Mac 
OS X quickly and with extreme quality, let our experts help. 

• Aqua Interface Implementation 

• OS X Carbon Porting 

• OS X Native Cocoa Application Development 


R E dQo C I 

soj'lwa re 

call Red Rock at 888.689.3038 
or visit us online at www.redrocksw.co 




□ Eat your vegetables. 

□ Exercise every day. 
^ Port to Mac OS X. 

□ Call your mom. 


All of these are good for you. 
We can make one of them easy. 

Since 1989, The Omni Group has worked with the technologies that have been reHned into Mac 05 X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That's been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

« Real games: We ported Id's Doom and Quake games to NEXTSTEP and X. Quake 2 took us a week. 

• Big apps: We ported Adobe's FrameMaker to NEXTSTEP and Sun's Concurrence to OpenStep/Solarls. 

• Big libraries: We ported the Oracle 8 client libraries which j^yple ships today in X Server. 

• Solous drivers: We ported Sdfx's Glide and wrote Voodoo2 juid Rendition ckiv^s for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpmiStep. 

• New apiK: We wrote OmnlWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac X is what we do. Let us help you do it, too. 


I HE Omni Group 
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The table below lists, for each of the solutions 
submitted^ the late-dollar-days value produced by the 
combined test cases, the cumulative execution time^ and the 
number of reconciliation records generated. It also provides 
the code si2e, data size, and programming language used for 
each entry. As usual, the number in parentheses after the 
entrant's name is the total number of Challenge points 
earned in all Challenges prior to this one. 

Name Soap's Time Records Errors? Code Data I^ing 


(msecs) 



Si!«: 



Ernst Munter (66D 1829792 0,43 

679 

IKl 

2756 

180 

C++ 

Sue Flowers 1829792 

712 

no 

4156 

233 

C 

A.D. 44^2680 0,78 

11 

yes 

1272 

24 

C++ 

R. S. 


crash 

138.55 

1775 

C++ 


Top Contestants ... 

Listed here are tlie Top Contestants for the Programmers 
Challenge, including everyone wiio has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month’s entrants. 


... AND THE Top Contestants Looking for a Recent Win 

In order to give some recognition to other participants in 
the Challenge, we also list the high scores for contestants 
wdio have accumulated points without taking first place in a 
Challenge during the past two years. Listed here are all of 
those contestants who have accumulated 6 or more points 
during the past iwo years. 


Rank 

Name Points 

Rank 

Name Points 

9. 

Dowms, Andrew 

12 

16. 

Strc>ui, Joe 

10 

10. 

Jones, Dennis 

12 

17. 

Hala, Ladt-slav 

7 

11. 

Day, Mark 

10 

18. 

Miller, Mike 

7 

12. 

Duga, Brady 

10 

19. 

Nicolle, Ludovic 

■7 

13. 

Fazekas, Miklos 

10 

20. 

Schotsman, Jan 

7 

14, 

Flowers, Sue 

10 

21, 

Widyatama, Yudhi 

7 

15. 

Selengut, Jared 

10 

22. 

Heithcock, JG 

6 


There are tliree ways to earn points; (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first f^rson to 
suggest a Challenge that t tise. The points you can win are: 


LsE place 20 points 


Rank 

Name Points 

Rank Name 

Points 

2ncl place 

10 jX)iiiLs 

1. 

Munter, Ernst 251 

5. 

Boring, Randy 

yr 

3rd place 

7 points 


Saxton, Tom 96 

6, 

Shearer, Rob 

48 

4t[i place 

4 points 

3. 

Maurer, Sebastian 68 

7. 

Tiylor, Jonathan 

36 

5tli place 

2 points 

4, 

Rieken, Willeke 65 

8. 

Wihlborg, Claes 

29 

finding bug 

2 p(3inLs 


sugge.sting Challenge 2 points 
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libraries, templates, algorithms, toots and much more. It also provides over 
250,000 code lines, the complete CAD++ library with classes and functions 
to design CAO applications. Garbage Collection-based 
classes, nested clecses. UML/C++ models and morel 


’“C'-l l- Kti tfWf/ViVf wi (if tiHfh httifti sifjiwart' i tmjitriiis 

itt C++ Matt jiird\. Ttm aha iirtp.s Mthr prahiriax thataufffu 

cwtT/,v in ttevfhfpntcM fftr Mtfinart rvpfmas tbt'fumt&HtnUah itfiK^fL aitU 
(Mf diaTfttfmrif/ tritii a ranrfy w/ ihwA'A aati applU atum.n. ** 


miDETHEKfl 
3 CDs 
Z t/lanuBh 
1UMUC*-* Quteif Reference 


mtUDBS 
C++ guide 
C++ fools 
C++ snrppefs 
C++ (jnyeefs 
C++ ciesses 
C++ Web Sites 
UML sfentJ^ntf 
UML seminar 
Ui/li imdeis 
SR titrsry 
OOP tapks 
Software Reuse 


^ If] rrfufe of Ekctrkal & 
" Electronics Ertgimers 


COMPUTER 


Hn^HSSil INSIDE 
' jw ^ ^ 


Try oxif free C++samp/e code af: hdpiU\f^wwMchr\Q%oitmib,ccmiQ++ 

«ay!fE_ 


tlcv^KT’S 

f+tn^ 


TECHNOSOJFT _ 

mailto: orders@i^hnoBaftweb.com 

www.teclinosoflweb.com 



FREE shipping 

^Of f ijijafHu.Cfrf, USJ CAN/4MJ 

































Here is Erast's winning ''What Bills Did They Pay'' solution: 

WhichBillsxp 
Copyright © 2000 
Ernst Munter 

r 

OctoberC2000. 

Submission to MacTech Programmer's Challenge for October 2000. 

CopjTight © 2000, Erast Munter, Kaoata, ON, Canada. 

“What BlJJs Did Thq Pay 

The Problem 

Reconcile a set of invokes and payments where invoices may be paid with more than 
one instalment, and where payments may cover several invoices. 

The objective is to minimize the overall ‘'late dollar days’' subject to a set of rules. 

The Solution 


1 tackle the problem in tliree passes over the lists of Invoices and payments. During 
tile first and second phases, reconciled invoice and payment records are removed 
from the Usts. 

[n the first pass, each payment may 

' be perfectly matched to a sM^e invoice, 

- exactly match the sum of a number of invoices, 

* not match. 

In the second pass, any remaining paj^menis are applied to the smallest available 
invoice. This may still leave unmatched invoices or payments unreconciled. 

The amount oflate dollar days" is the sum of each reconciled amotini midtiplied by 
the delay between the invoke and die payment. 

The''late dollar days" figure includes each of the remaining unmatdied invoices, 
multiplied by die delay from the invoice date to the last payment date. 

Any left-over paymeni that catmot be reconciled is disrcgaided. 

Minimization of‘'late dollar days'* 


Tf all payments have been accounted for, the resiilting "late dollar days'* number is 
independent of die how the payments are applied to the invoices. This is true 
because all unpaid invoices are effectively^''paid" off on the lost payment day. 

The objective (to minimize "late dollar days ') Ls thus achieved wdicn all payments are 
matched against invokes. If this is not possible, it is best to 

- minimize the number or amount of unmatched payments, 

- leave the invoices that caimot be matdied to as late a date as possible. 

No exhaustive attempt is made of legal permutations of multiple and partial matches, 
to eliminate ALL unmatched payments. It is hoped that the heuristic approach comes 
Mrly close, 

7 

j'^iiclude '‘RoeoncilePayffients. h” 


struct Calendar 

// Linear calendar for calculating differences in davs 

const char months[i2]=[0,31.2&,31*30'31,30,31,31,30,31*301t 
static struct Calendar { 
short startMonthl4][16]: 

Calendar() 

I 

for (long y^0:y<4:y++) 

1 

startMonthly][l]=Q: 

startMonth[y][2]“months[1]: 

startMonth[y] [3]=startMonth[y] [2]+mcinths(2j; 

if (yr^O) startfionth [y] [3]-H-; 

for (long iD“4;in <= 12 3 ++) 

startMonth[y] [tn]^startMonth[yj [m-l]-hnonths tm-1]; 

1 

1 

] gCalendar: 

// Gonvcfis a Macintosh 14-byte DateTimeRec into a long (resolution to days only), 
inline long DayNumber(const DateTimeRec k x) 


return 

(1461*x,year-1)/4+ 

gCalendar.startKonth[3 & x.year][x.month] + 
X.day r 


struct Myinvoice 

// My version of the invoice, using linear dates 
struct Myinvoice [ 
long amount; 
long day: 

Myinvoice * next: // Invoices art stored in a doubly linked list 

Myinvoice* prev: 
long number: 

Myinvoice[)11 

Myinvoice(Myinvoice* nxt*MyInvoice* prv) : 
amount(0), dayfO). 
next(nxt)* prev(prv), 
number(0)[ 1 

Myinvoice(const Invoice k Inv.MyInvoice* nxt,Myinvoice* prv) ; 
amount(Inv.invoicsAmount)* 
day(DayNumber(inV*invoieeDate)), 
next(nxt). 
prev(prv), 

number[lnv,invoiceNuraber)f1 
void Remove{) 

// bridges link pointers to remove invoice from tlie list it is on 

i 

if (next) next*>prev=prev: 
prev■>next=next; 

// prev is never 0 except in the list root which is never removed 

f 

I: 

typed G f MyInvoic e * MyInv oic eP t r: 


struct MyPayment 

// My version of the payment, using linear dates 

struct MyPayment I 
long amount; 
long day: 

MyPayment* next: // payments are stored in a doubly linked list 

MyPayment* prev; 
long number; 

Myinvoice* mostRecentInvoice; // ..relative to this payment 
MyPayment 0 11 

MyPayment(MyPayment* nxt*MyPayment* prv) r 
amount(0). day{D)* 
next(nxt), prev(prv), 
numb e r(0), mostRec entInvoic e{) [) 

HyPayment(const Payment & pay.MyPayment* nxt*MyPayment* prv) : 
amount(pay,paymentAmount)* 
day(DayNumber(pay * paymentDate)). 
next(nxt), prev(prv), 
number(pay.paymentNumber), 
mostRecentInvoiceO (] 
void Remove0 
[ 

if (next) next->prev=prev: 
prev-)next=next; 

I 

h 

typedef MyPayment* MyPaymentPtr; 


(lount 

Inline 

long Count(const Invoice theinvolces[]) 

// Counts the number of invoices, up to the sentinel with invoiceNumber 0 
\ 

const Invoice* l=theInvoices-1: 
long n-0: 

while ({++!)->invoiceNtjmber) {n++:l 
return u: 

] 

inline 

long Count[const Payment thePayments[]) 

// Counts the number of pavments, up to the sentinel with paymentNumber 0 

I 

const Payment* F=thePayments'1: 
long n-0: 

while ((++P)->paymentNumber} ln++;l 

return n; 
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Reconcile 

inline 

long Reconcile(long amoimt.Reconciliation & R. 

MyInvoice & I.MyPayment & P) 

// Copies info into a reconciliation record and returns late dollar days 

long iAmonnt^I. amount: 

// long pAm(3uni-Ramount; // there is no need to track panially used payments 
R.paymentMumber^P,number: 

R ,app1iedAmount^amount: 

R. invoiceNumber^I.number: 

1.amount = iAraount amount: 

// Ramount = pAmoniit ^ amount;// there is no need to track partially used payments 
return amount *(P.day-I.day); 

] 


Combinelnvoices 

inline 

MyInvoicePtr* 

Combinelnvoices[long balance,Myinvoice* I. 

Hyinvoice* mostRecentlnvoice.HylnvoicePtr'^ stack) 
// Searches invoices, from the range of invoices up to "mosiReeen tin voice" to add up 
// to "balance" 

// The result is a sublisi on die stack, 

// Returns the top of the stack, or 0 If no match was found. 

I 

‘Etack=0: 

MyInvoicePtr* SP=3tack+l: 

while {I && {I<=mostRecentInvolce)) 

[ 

if (balance < I '>aniount) // invoice too large: tr>^ next in Bst 
( 

I=I->next: 

if [ [I>moBtRecentInvoice] | | (1^0)) // reached end of range 

1=* -SP: // unwind stack 

If (1=0] return 0; //reached bottom: no multiple found 

balance += I-)amaunt: // restore previous balance 
I=T - >next; // and try next in list instead 

I 


continue: 

I 

if (balance > I->amQunt) //include thb one perhaps 
[ 

if (KtnostRecentlnvoice) 

// it’s in range, and there is at least one other 

[ 

* SP+-H^1: // push this invoice on stack 

balance -= I->amount; 

I”l->next: 

I el se //go back to previously found and skip It 

I 

1“ “S P; // unwi nd stack 

if (1=0) return 0; //reached bottom; no multiple found 
balance += I->amoiint: //restore previous balance 
I-I - >next; // and try next In list instead 

I 

continue: 

1 

if [balance = I->amount) //success 

( 

‘ S 1: // push this invoice on stack 

return SP: // and return stack 

] 

] 

return 0: 


PartialRiyment 

inline 

Mylnvoice’' PartialPayment [long balance,My Invoice* I, 

Myinvoice* mostRecentInvoice) 

// Returns the first invoice that exactly matches the balance, 

// faUing an exact match, returns the invoice with the closest higher amount. 

// Returns 0 If no exact or partial match is found, 
f 

My Invoice* befltl"=0: 

long bestAmount=0x7FFFFFFF: 

while [I (I<=mostRecentInvoice)] [ 
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if (l'>araoL3nt balance) 

I 

return I; 
f 

if {I->a!!iount > balance) 

[ 

if (r->aiiiount < bestAinoiint) 

( 

bestl="l; 

beEtAmount=I- >ainDunt; 


I=r->next; 

] 

return besti: 


ReconciltPa>mcnts 

long ReconcilePayments ( 

const Invoice thelnvoices[]. 
const Payment thePayments[] * 

Reconciliation theReconciliation[] . 
long numberOfReconciliationRecords, 
long *lateDollarDays ) 

// Attempts to reconcile all invoices with the payments and imputes the 

// lateDoliarl>ays. 

// Returns the numlier of ReeonciliatbnRecords actually filled out. 


U Prepare private copies of Itivoices 

long nuoiInvolcea^^Count [thelnvoices) : 

Mylnvolce' IHV ^ new Hylnvoice[numinvoicesh 

Mylnvolce^ 1 “ INV: 

const Invoice* thel = theinvoices; 

Hylnvoice iList=HyInvoice[TNV,0): 

Hylnvoice* laostRecentlnvoice = ^iList; 

// Link all invoices into a list 

for (int i“D:i<nnmInvoiceg:i++,theI++) 

( 

Hylnvoice* ne>ttInvolce=I+l: 

*I=^Hyinvoice{*thelnoextInvoice,mostEecentInvoice) t 
piostRecentInvoice”I: 
l=nextInvoice; 

] 


mostRecentlnvolc e->next=0; 

// ib-epare private copies of payments 

long numPayments^^Gount (thePayments): 

MyPayment* PAY = new HyPayment[numPaymentsj : 

HyPayment* P = PAY; 

const Payment* theP = thePayments; 

MyPaymen t pLis t=MyPayment(PAY,0) : 

MyPayment* lastPayraent = ^pList; 

// Link all payments into a list 

for (int p=0;p<numPayments;p-H‘,theP++) 

i 

MyPayment* nextPayment=P+l; 

*P = MyPaytnent [*tbePHnextPaynient, last Payment); 
IaatPayment“P; 

P^nextPayment; 

1 

lastPayment->next=0; 
long lastPayday={-P)-)day; 

Reconciliation* R = theReconciliation; 

// shorthand for a long variable name 
long maxR = numberOfReconciliationRecords; 

// shorthand lor a long variable name 

// Get memory for a stack for the non-recursive search 
long fitackSi 2 ;e=l + numlnvoicea; 

MyInvoicePtr* iStack-new MyInvoicePtr[stackSize]; 

long nmoR^O: 
long lateDD^O; 

r PHASE 1 

Sc;m all payments, tiding to match single or multiple invoices against them 

7 

for {P=pLiEt,next; P; P^P->next} 

[ 

I=iList*next: 

if (1=0) break; // in voice Ibt Ls em ply: we’re done 

long amount^P■•>amount; 
long theDay=P->day; 

// scan fom'ard througli invoices to find a peiftct maich for a single invoice 

Hylnvoice* perfectMatch=0: 

mostRecentrnvoice={}; 

while (I (I“)day <" theDay)) 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- Vie w-Controller 

AppMaker's generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the ’aete’ resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B'0*W*E*R»S 

Development 
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MacSOHO? 
It rocks! 


THURSBY SOFTWARE has the 
perfect file share solution to 
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to share files. 
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files and printers between 
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Don't l«t this 
ai^ntospou. 


Stay suited up with The Regulator Pro™ UPS 
for Macintosh* Computers from Belkin. 

The Coast Guard calls it Semper Paratus—always 
prepared. To us, it's the Regulator Pro Gold Series. 
Belkin knows you can't afford to risk your data and 
hardware to unpredictable forces like blackouts, 
brownouts, spikes, and surges. With a Data 
Recovery Warranty, a Connected Equipment 
Warranty, and up to 45 minutes of battery back-up 
time, as well as the great features listed below, 
we're here to make sure you won't 
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• Automatic Voltage Regulation (AVR) 
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if (r->aincimit = aMotint) 

{ 

perfectMatcli=I: // break on earliest match found 

break; 

mo s tRe c en 11nV 0 ic e=I; 

I^I->next: 

) 

F“>mostRecentInvGice^ostRecentInvoice; 

// side effect: gets invoice range ft>r each payment 

// use earliest perfect match if there is one 
if (perfectMatch) 

( 

lateDD Reconcll e[amount .R{nuffiR-++] .* perfectMatch* *P); 

P - >Remove (); // remove payment from list 

perfectMatch’>RetEDve(); // this invoice can be imoved 

if (nuiitR >= maxR) //all available recRecords used: must quit 
goto phased: 
continue: 

1 

// xjy combining multiple invoices 
MylnvoicePtr^ SP= 

CdiEbineInvoiceg(amount,iList,next,mostRecentInvoice.iStack): 
if (SP) 

I 

P - > Remove 0; // remove payment from the list 

I=’‘-SP: // pop one invoice from the stack 

do \ 

latePD Reconcile {I->amount *R[niiniR++] I. *P) ; 

I - > RemoV e (}; /f this invoice can be removed 
I=*-SP; // pop next invoice from the stack 

if (nuraR maxR) //ail available recRecords used: must quit 
goto phaseB; 

1 while (I)t 

} 

I 

/•PHASES 

Scan remaining payments, trying to match them as partial payments against the 
remaining invoices 
7 

for (P=pList,next: P; P=P->next3 

f 

I=lLiEt.next: 

if {1=0) break: // no invoices left to balance: next phase 

long aBiount=P-)amount; 
long tlieDay“P')day t 

// find''best*'partial pajtnent 

ImpartialPayment(amount.IList.next,P-)mostRecentInvoice); 

if CD 

( 

P'')Reniove C) I 

lateDD += Reconcile (amount. R[niiffiR++] , ‘I. *P); 
if Cl->amount=0] 

I->Reroove(); 

if ( numR >= maxR) //all available recRecords used: must quit 
break; 

] 

} 

/*pa\SE3 

Scan remaining invoices, adding tliefr unpaid balances to the late dollar daj's 

V 

phase!; 

far [I = iLiat.next; I; I“l-)next) 

lateriD+= (lastPayday -1 - >day) * I - >ainount; 

// free dynamic memory 
delete [] iStack: 
delete [] PAY: 
delete [] INV: 

*1ateDoliarDays = lateDD; 
return numR; 
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// Like most Mac developers, 

// I easily spend 12 hours a day 

// staring at line after line of C++ code in tiny, 9 point Monaco. 

// Sometimes it makes my eyes feel like they’re on fire. 

i 

So the last thing I need is some 
fuzzy monitor that adds to my headaches. 

I 



/•••••• begin excitement ••••••/ 

// That's why I'm so jazzed about this SGI monitor. 

// Its ultra-high resolution = t6oo x to2Z| and dpi = no. 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
// perfect for poring through lines of code. 

// At first, I was amazed at the clarity, the fine details that emerged. 

I 

It wa6 like seeing thing6 for the fir<>t time. 

I 

// Later, though, I learned to appreciate the wide aspect ratio |= i6:io|, 
// with a generous 17.3 inches of viewing area. SGI’s 1600 SW 
// lets me have alt my documents viewable at once, and it's 
// a flat panel so it fits on my desk with room to spare. 


// From the moment I saw this thing I was hooked. You will be, too. 

I 

Especially when you find out 
how affordable it is. 

// Check it out. 

/•••••• end excitement ••••••/ 
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MAC OS X 


By Andrew C. Stone 


Dynamic Bundles and Runtime 
Loading in OS X 


As an application gets larger and 
more complex, the end user may 
perceive that the application loads 
slowly. Of course one can throw faster 
and multiple CPUs at the problem^ but 
if you take advantage of dynamic 
bundle loading, your application can 
grow in functionality, but the time to 
launch remains lightning quick. How is 
this done? Simply by only loading the 
resources the user really needs at the 
moment. This article will show you how 
to architect your application to cake 
advantage of bundles and late-loading. 

Consider the fact that a typical 
application may have dozens of 
special panels and facilities that are 
occasionally accessed by the end user. 
There is no reason to load either the 
code or the resources for these panels 
until the end user actually requests 
that functionality. 

There are many advantages to an 
application that dynamically loads 
bundles besides just fast launches. For 
example, in Stone Create, not only are 
all the inspectors, panels, and editors 
loaded on demand, but there is also a 
facility to load new tools at runtime. 
Any bundles found in the Tools 
directory are loaded and added to the 
tool palette when a new document is 
created. For example, the "Star” and 
''Embed" objects are loaded this way. 
New tools can be created and added 
without Create knowing anything 
about these in advance. By creating 


and adhering to protocols, which are sets of methods that 
must be implemented by an object, your application can 
deal with brand new objects at runtime. 

The CFBundle, and its Cocoa cover class, NSBundle, 
handle all the details of locating and loading resources on 
demand. Most developers just use these for user interfaces, 
images, sounds and resource files, but ifs simple to also load 
code on demand. The question then becomes, “how can 1 
refer to code that is not yet loaded?" and “how can I compile 
code that has unresolved symbols"? 

PREFEHENCESCONTROLLER BUNDLE EXAMPLE 

One feature which makes OS X applications so powerful 
is the ease of user customization through the NSUserDefaults 
mechanism. Therefore, most applications require a user 
interface for preferences, but why load this panel and the 
code which controls it before it’s absolutely needed if at all? 
Well use tlie example of a preferences panel as a likely target 
for “bundling". The object "PreferenceController” is an 
NSWindowControiler subclass, which knows how to return a 
single instance of itself with a factory method, 
+sharedlnstance:, because there is only one preferences 
panel in any application: 

+ (id)eharedlnstance I 

static PrefcrencesContraller 'sharedPreferences = nil: 

// the first time through, we get the singleton preferences conttollcf: 

if (! sharedPrefarences) [ 

sharedPreferanees = [ [PreferencesController 
allocWithZonerNULL] init); 

I 


return sharedPreferances: 


Our dynamic loading code will assume that every 
bundle responds to "+ sharedlnstance’' if there are only 
one of these objects {for example, there is only one Color 
panel per application). 


Andrew Stone <Endrew@ stone .com> is CEO of www.stone.com and has been working with Cocoa since 1989 ^ith its 
introduction as NeXTStep. 
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If PreferenceController is linked into the application, 
you would have a method to bring up the panel in your 
application delegate object: 

- (IBAction) showPref erencesParielAction: C±d) sender I 
[ tPrefereneeController sharedlnstance] 
showWindow:self] ; 

} 

but then, that code would be loaded at the launch of 
the application, because it has to be compiled into the 
application's binary since it is referenced by name. The 
way we move to a dynamicly loaded model is to never 
refer to this class, except in a string as an argument to our 
dyamic loading method sharedInstanceOfCiassName:, 
which appears later in the article: 

[ [self 

sharedInstanceOfClassHame :#'*PreferenceaContrQller"] 
showWindow:self] : 

Now, the code will compile without including the 
PreferencesController class. Our job is to be sure it gets 
loaded when first needed. Typically, T add the bundle 
loading code to the NS Application's delegate, which can 
be globally accessed with: 

[NSApp delegate] 

Another strategy, and a topic of a later article, is to 
use categories, and add that functionality right to ±e 


NSBundle class, T prefer using the NSApp's delegate 
because you can add cover methods for loading panels in 
a single class, and then connect menu items to the 
instantiated application delegate in the application's main 
NIB file. So, in this example, we would: 

1, add a method to the NSApp delegate class: 

' (IBActioti) EshowPreferfineesPanelAction: (idjsfindfit: 

2, In InterfaceBuilder, connect the menu item 
“Preferences,..” to the app delegate target, with the 
action “showPreferencesPanelAction:”, You can quickly 
add actions to IB by dragging in the .h or .m file from 
ProjeetBuilder into the document window of your nib. 
This is equivalent to “Classes->Read File..,”. 

3, When that menu item gets triggered, the application 
delegate will load the needed code. Subsequent 
invocations of the panel will be even swifter, but 
loading a single panel and controller code is pretty fast 
anyway. 

Bundle Integration in Project Builder 

From a Project Builder standpoint, your applica.iion’s 
project becomes an aggregate of targets: the application 
target, and a target for each of the dynamically loaded 
bundles. Your application should add the product of each 





www.funnelvtfeb4.com info@activeconcepts.com Toll free 1800 551 5282 


Speed, intuitive user interface, accuracy and in-depth analysis have always made 
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bundle to the Copy Files phase in the “Files and Build . (id)instanceO(c:assNai!ie; (usstring Mnama [ 

Phases'’ tab of the application tar^get inspector. return [self instanneOfClasaNamemame sharediNO] : 



Figure L Copy files phase adds bundles 
to the application target. 

For backwards compatibility with OpenStep, I use the 
^'Resources’' direaory to store bundles. The following code 
ai^sumes that you are putting your bundles into the Resources 
subdirectory in <YOUR_APP„NAME>.app/Content5/* You 
change where they are copied to with the ''Wliere:'’ pop-up 
in the Files & Build Phases pane of die Target Inspeaor. It is 
probably more intuitive to place bundles in "Bundles'* 
subdirectory, and if you do, change the 
pathForResource-ofType: call to pathForBundleiofType: in 
tlie method -(id)instanceOfClassName:(NSString *)name 
shared:(BOOL)shared. 

Before looking at the very simple dynamic loading 
code, there is one point to consider A Cocoa bundle 
has the notion of a principal class. That is the class that 
is both the owner of the NIB file, and the class that 
needs to be accessed first when the bundle is loaded. 
Many times, a bundle wall only have one class in it, but 
its a potential gotcha to not specify the principal class 
if there are more than one class in the bundle. You 
assign the principal class in Project Builder - click the 
bundle target to load the target inspector. Select the 
"Bundle Settings'’ tab, and under the '*Cocoa Specific" 
settings, type in the name of the class in the Principal 
class field, in this example, PreferencesController. 
Other fields let you assign version information, help 
files, main nib files, but these are optional. 

The Dynamic Loading Code 

The code offers tw^o types of dynamic code loading 

- both singleton class instances such as the 

PreferencesController with 

sharedlnstanceOfClassName, as well as simple new 
instances for each invocation whth 
instanceOfClassName. Both use the same core code 
with a "shared" flag: 

- [icDsharedlnstanceOfClassName: (NSStrltig *)naii]e 
i 

return [self ±nstaiiceOfClflssName:narte aliai:ed:YES]; 

1 


instanceOfClassName would be used, for 
example, in a document-based architecture application 
where each document had its own version of that 
bundle’s nib. An example would be a sheet that gets 
run on a per-document basis — because more than 
one document can be in a sheet-modal state at the 
same time. In this case, the document becomes 
responsible for freeing the bundle resources upon 
closing. Singleton instances are not freed until the 
application quits. 

- (Id) instanceOfClasslSIanie : (NSString *)narae 
shared:(BOOL)shared 
[ 

id obj “ nil: 

// NSBundle does the work of finding the bundle 
// pathForResource means ‘'look into Resources folder" 

// use pathForBundie If you store them in the “Bundles'* folder 
NSString *path - [[NSBundle mainBundle] 
pathForResource: name. 

ofType:©"bundle"]: 
if (path) { 

NSBundle *b = [[NSBundle allocWithZone:NULL] 

InitWithPath: path] : 

// the obiect we wish to return is an instance of the principal 

class: 

if ((b E- nil) ( [b principalClass] 
l-NULD) f 

// we either grab the sharedlnstance or create a new one: 
if (shared) obj = [ [b principalClass] 
sharedlnstancej : 

else obj = t [ [b prlncipalClase] 
allocWithZone:NULL] init]: 

// provide Developer feedback if something has gone wrong: 

} else NSLog(@"Can*t Load %@l\n". path): 

} else NSLog(@"Couldn"t find 
bundle! \n" .name); 

return obj: 

) 


Conclusion 

When designing your application, it is good practice 
to decompose your functionality into smali, loadable 
pieces. By using dynamically loaded bundles, you gain 
launch speed and can take advantage of runtime binding 
for loading new^ tools. Probably most importantly, 
bundles create a firm foundation for future feature growth 
without application bloat as w'ell as provide a natural 
modularity that is easy to comprehend. Si 
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WEBOBIECTS 


by Sam Krishna and Patrick Taylor 


Finding Fault 


Why the EOFaulting mechanism neatly 
solves a thorny problem in the Object- 
Relational paradigm 

The Object-Reiational paradigm is the conceptual 
foundation to the Enterprise Objects Framework (EOF). 
Concepts such as tables map nicely to classes, rows to objects, 
row-column values to instance variables (ivars), etc. The 
mapping is so neat and clean that one is rather surprised to find 
a terrible flaw marring the paradigm. 

One difficulty is that few simations are easily encompassed 
by single, isolated tables. A relational approach is frequently 
needed. However, having started down the Object-Relational 
path, what happens to objects that are related to other objects? 
What happens if a large set of objects is related to a single 
object? How can these relationships be represented without 
compromising performance or overwhelming system memoiy^? 

In real life, relationships are numerous, complex and 
widespread. Consider a (simplified) model of a credit card 
reporting application. 

Consumer Credit Card ^Purchases 


Payments 

How would such an application be able to traverse from 
Consumer to Purchases without swamping the memory 
footprint^ If we tried to apply this model to 200 million 
individuals charging approximately USSl 0,000 per year on 3 
credit cards (on average), the situation could get nasty in a hurry. 
Imagine fetching 600 million rows into an application in order to 
traverse the relationship graph for a credit card query. What kind 
of memory footprint would be needed to do a report on the 
purchasing information? When the program exceeds memory 
requirements, the machine will grind to a stop. 


W'ithout an efficient way of accessing our program's data, the 
value of die application comes into question. The types of 
applications created by WebObjects depend on a reasonable amount 
performance, but an elegant objea-relational mapping is a useless 
affectation if it becomes an albatross. Object-orientation is not an end 
in itself, but rather a means — preferably a superior means. 

Fortunately for us, the EOF engineering team solved this 
problem using a mechanism called the EOPault class and its 
EOFaultHandler. Together these classes form a system where 
light placeholder objects are substituted for regular objects before 
they are fetched. The EO Fault is a raincheck, promising to fetch 
the real objecLs when actually needed. 

READY-AlM-FmE! 

If you wish to fetch a related row in EOF, a fault has to be 
Fired, Before you get the idea that this is extremely complicated 
in either theory^ or practice, stop fretting, It isn't. You simply 
“walk" the relationship graph and, most of the time, your 
WebObjects application will do this for you. 

Take a look at the Movies example model that ships with 
WebObjects. Let's assume that you need to get a list of movie 
roles for any given movie that is selected. After fetching a 
particular movie, let's take a look at the movieRoles relationship 
before the fault is fired: 

JayaBebug)^ po movieRoles 

movieRoles = CArrayFault(0xl95Gfc8) source: [GIB: Movie. 
(155)] relationship: movieRoles > 

As you can see, movieRoles is an AnuyFault which kncw^s to 
fetch all the rows on die destination side of a to-many relatioaship 
named movieRoles. The GiD refers to an EOGloballD, an object 
that contains the primary key information within Movie that is 
needed by the faulting system to fetch die related rows in the 
movieRoles table. When the fault is cleared or fired, EOF generates 
the SQL necessary to fetch the related rows. Wliat is cool is that you 
don't have to write any code to fire diese faults, WebObjects/EOF 
simply knows how to fault reladoaships automagically with very little 
(if any) programmer intervention. 

At this point, your pnjgram might need to ask which studio 
produced which movie. It can do this by faulting the movie's studio 
relationship, Here’s what the fault will look like before it is fired: 

movie.studio is <EOGenericRecord(0x2057c98) Fault [GID: 
Studio. C9)l> 
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Once the studio fault is fired, EOF will again automatically 
generate the SQL, fetch the related row, stuff the results in a 
brand new Enterprise Object (EO), and return the new EO to the 
WebObjects Movies application. 

Batch Faulting 

If the Movies example was a real application with real users, 
then it's quite likely that someone would wish to see a list of 
credits for the movie's actors. This isn't an unreasonable demand 
since WebObjects will traverse the to-one relationship from the 
MovieRole EO to the Talent EO, The problem however is similar 
to the one we discussed in the credit card example. When you 
deal with a situation where many roles are getting fetched 
individually on an application getting a million hits per day, you 
need to do something to minimize the number of round-trip 
fetches to the database. 

Every time a fault is fired, a round trip to the database is 
made. If your Movies application had 1000 users, each one of 
which looked at about 10 movies per visit, and each movie had 
a cast of 20 actors, your application would face approximately 
200,000 round trips to the database for the cast list alone. Batch 
faulting is a great way to rein in your application's demands, it 
can potentially reduce the number of round trips to 10,000, The 
more relationships hanging off, the bigger the bang for batch 
faulting, Fm sure that you1l agree that a twenty-fold reduction is 
nothing to sneeze at! 

One way to batch fault is to set the number of items you 
want faulted in a to^many relationship using EOModeier's 
Advanced Relationship Inspector, While a terribly convenient 
approach since this allow^s you to fault lists without WTiting code, 
it unfortunately won’t help us in this particular example. 


Prefetching 

Prefetching is an alternative method for 
faulting. It is used specifically with an 
EOFetchSpecification, which we will discuss in 
more detail next month when we cover the 
EOEditingContext. Suffice to say, it is a pre¬ 
empting action to the faulting mechanism. 
Based upon the key paths you feed to a 
particular EOFetchSpecification, you will be be 
able to prefetch EOs based upon the 
relationships from a particular set of entities 
you are fetching. 

A developer must take care when using 
prefetching because it is too easy to fetch 
unnecessary EOs without thinking about it It is 
better to profile the kinds of fetching patterns 
that occur during use of the web application 
before setting prefetching key paths upon the 
EOFetchSpecification, the class used with the 
EOEditingContext to fetch objects explicitly. 

The method on the EOFetchSpecification class for 
prefetching, setPrefetchingRelationshipKeyPatbsQ, 
(setPrefetchingRelatiomhipKeyPaths: in Objective C), 
takes an NSArrc^ of relationship keys. For example, if 
yiou wanted to prefetch both the movieRoles arid 
studio relationships, you can pass the strings 
"movieRoles” and "studio" in an NSArray 
C&'movieRoles" and ®"studio"in Objective Q. 

One thing to keep in mind, if you set an 
EOFetchSpecification to refresh through the method 
setRefresh e sRefe tchedObjectsO 
(setRefreshesRefetchedObjects: in Objective C), any 
refetches are propagated through the object graph 
(meaning that both studio and movieRoles ivould 
be refetched as well to update the current state of 
the object graph as reflected in the database), n 


> INTERNATtONALIZATIOM ^ LOCALIZATION 


a I2& U* 122 120 U8 lie H4 112 UO lOB lOO 104 1Q2 100 9$ Ve 34 92 90 m 



vision 


International 
Software Solutions 


Don't overlook the global possibilities of your product. If you are 
venturing into international markets for the first time, or updating a 
previous version of your software, we can help you get to market 
quickly with a fully localized product Geotopia offers a broad range 
of internationalization and localization services supporting all aspects 
of your product, customizable to meet your exact needs. Call us 
today for a free consultation. 

TEL: 800,553.2275 i 801.796,2124 wEfi: www.geotopia.com 


geotopia'“ 















Programming Doesn't Have 
To Be This Difficult. It's REALbasic! 



REALbasic is the award-winning, visual^ 
object-oriented BASIC development 
environment for the Macintosh. 


Use REALbasic's visual interface builder and platform-independent 
language to build native, compiled—not interpreted—professional 
quality applications in a fraction of the time it would take in C/C-h-. 
Because our language is platform-independent you only need to 
write a single set of code to create applications for both Macintosh 
and Windows. Leverage your C/C-h- experience to esdend 
REALbasic's capabilities using shared libraries, Mac OS Toolbox 
and Win32 API calls or by writing cross-platfonn REAIhasic plug-ins . 

Create prototypes, Internet applications, database front-ends, even 
games with REALhasid Its OOP language employs everything 


you’d expect from a modem development environment—methods, 
properties, classes, subclassing, inheritance, constructors and 
destructors, virtual methods, and more. The IDE supports multi¬ 
threading, extensibility, TCP/IP controls, plus multimedia and 
QuickTime tools, and support for standards such as SQL, ODBC, 
AppleScript, and XCMDs. You can even import Visual Basic forms 
and modules. 

Go to www.realbasic.com NOW to download a FREE 
trial version or call 512.263.1233. 

REALbasic 







20® Rirnw-MJ - Bosf ^tecrttHh IJfea'E tobIb^ 


*Free update fof all owneis of flEALbasic 2.0 and above. REALbasic and the REALbasic logo ane trademarl!^ of REAL Software, inc. Apple and the Apple logo 
are trademarks of Apple Computer, Inc, registered tn the US., used with permission. All other tradernarks are the propedy of their respective owners. 








We need to programmaticaily fault a whole array of Talent 
reiatirjnships based upon the MovieRole entity all at once. To 
achieve this, we message the EODatabaseContext with the 
batchFetchKelationshipO method 

(batchFetchKelationship;forSourceOf:)jects:editingContext: in 
Objective C). It isn't always quite clear how to get the 
EODatabaseContext from the EOF stack for a given WehObjects 
application, worse yet, even after you retrieve it, there are still a 
number of other objects you must retrieve in order to send the 
message to the EODatabaseContext, Here is an example of how 
we batch laulted the Talent EOs as they w'ere related to an 
NSArray of MovieKoIes for a given movie: 

Java 

Be sure to import comuipple,yellow.eoaccess.* as one of 
your import statements 

protected NSArray raovieRolesO [ 

//An example of how to hatch fhiilL program mat icalty in Java... 

NSArray movieRoles = 

(NSArray)movie.valueForKey("movieRoles"): 

EOEditingContext ec = 
session 0.defaultEditingContext0: 

EODatabaseContext dc ” 

EOUtilities.databaseContextEorModelNamed(ec, 


■movies") : 

EOModei moviesModel = 

EOModelGronp,defaultGroup(),modelNamed C^Movies”): 

EOEntlty movieRoleEntity = 

moviesModei .entityNamed("MovieRole"'); 

EORelationshlp talentRelationship = 

movleRoleEntity.relationshipNamedC"talent"): 

movieRoles . cotint [) ; // Fires the array fauJt to be used for the second 
argument 

dc.batchFetchRelatlonship(talentRelationship♦ movieRoles. 
ec) : 

return movieRcles: 

] 


Objective-C 

Be sure to declare #iniport <EOAccess/EOAccess.h> as one 
of your import statements 

- {NSArray *)inovieRoles 

[ 

// Batch faulting example in Objective-C 

NSArray *mDvieRoles ” 

[movie valueForKey :@"movieRoles''] : 

EOEditingContext *ec = 

[[self session] defaultEdltingContextJ; 

EODatabaseContext *dc " 

[ec databaeeContextForModelNamed :@'"Movies"] : 

EOHodel *mQviesModel ^ 

[[EOModelGroup defaultGroup] modelNamed:0"Movies”] : 

EOEntlty *mavieRoleEntlty = 

[moviesHodel entityNamed:0"MDvleRole“] ; 

EORelationshlp '*talentRelationship = 

[movieRoleEntity relationshipNamedtalent"]; 

[movieRoles count]; 

if Fires the array fault to be used for the furSourceObjects: argument 

[dc batchFetchRelationshlp:talentRelationship 

forSourceObjacts:movieRoles edltingContext;ec]; 

return movieRoles: 

1 

Tliere are quite a few objects to message as pan of the 
EOF stack panicularly the various elements of an EOModeL 
However this sample ctxle yields the desired result which is 
a batch fault that fetches all the related TalentEOs 
simultaneously in a single round trip to the database. We 
decided to batch fault tlie talent relationship in this method 
for demo purposes only, in a professional development 
context, it would make more sense to refactor the batch 
faulting code into a separate method. 


Deferred Fautting 

New to WebOhjects 4.5 is deferred faulting, a 
perfiirmancefocused approach to dealing with 
faults. While incredibly interesting, we aren't 
going to be able to do it justice within the 
confines of this more general article. Since 
W04.5, all EOGenericRecords automatically do 
deferred faulting so you will definitely be 
hearing much more about it. B 
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what to look for in code 

A metliod will distinguish itself as a fault-firing method 
pretty quickly in a generated EO class file. In Java, all 
accessor methods will have the willReadO method in it. In 
Objective-C, you will see an accessor that reads [self 
storedValueForKey;®”someKey'1. Remember that all 
accessors in a generated EO class are fault^firing methods. 
If a fault cannot respond natively to a method without 
firing, it will fire and fetch the real object in order to fulfil 
the response. 

For array faults, the easiest way to cause the fault to 
fire is by sending the countO message to it (count in 
Objective C)- this will fire any to-many relation ship-based 
faults. If you need to fire a to-one fault, you can either 
send it a message that you know the original object will 
respond to, or you can send the fault a willReadO 
message. In Objective-C, you can send any variety of 
messages that the original class should respond to, or you 
can simply use the EOFauit class object to fire the fault by 
sending the [EOFauit clearFault:aFault] message. Almost 
any message that the original class will respond to should 
do the trick. 

Reverting an object back into a fault 

If you need to convert an object that was faulted back 
into its original fault (for example to redisplay the state of 
a relationship after recent editing), there are a few more 
hoops to jump through. You need to get the EOGloballD 
for an EO, stuff the EOGloballD into an NSArray, and 
send a message to the EOEditingContext telling it to 
invalidate the objects with that particular global ID. 

Here is some sample code to refault the MovieRoIe 
objects that have been fetched: 

Java 

ptiblic void refaultMovieRoles C) { 

//A&sumc movLcRofcs is an ivar 

EOGloballD gid = null: 

int i = -1: 

EOEnterprlseObject eo = null: 

NSMutableArray g±ds “ new NSMutableArray(); 

EOEditingContext ec = null: 

for (i " 0; i 'C movieRoles. count O : ( 

eo - movleRoles.objectAtlndex(i); 
ec - eo.editingContext0: 
gid = ec.globalTDForObject(eo): 
gids.addObjectCgid); 

) 

session().defaultEditingContext{) 

.invalidateObjectsWlthGioballDs(gids); 

return: 

1 


Objective C 

- (void)refaultMovieRoles 
( 

//Assume movieRoles is an ivar 

EOGloballD *gid = nil: 

Itit ± = -1: 

id eo = nil: 

NSMutableArray *glds “ [NSMutableArray array]; 

EOEditingContext *ec = nil; 

for (i = 0; i < [movieRoles count] : i-t+} ( 

eo “ [movieRoles objectAtIndex:i]: 
ec = [eo editingContext]: 
gid ^ [ec globallDForObject:eo] : 

[gids addObject:gldl: 

I 

[[[self session] defaultEditingContext] 

invalldateObjectsWlthGloballDs:glds]: 

return: 

} 

The invalidateObjectsWithGloballDsO method 
(invalidateObjectsWithGlobailDs: in Objective C) is very 
powerful. It invalidates the entire undo stack for tho.se 
panicuiar objects with the editing context. It also signals 
the underlying object stores that the objects will need to 
be refetched the next time those particular objects are 
accessed (just like what would happen for a pure fault). 

There are other methods, such as 
invalidateAllObjectsO (invalidateAllObjects in Objective 
C), which will completely discard all EOs in the editing 
context as well as dump the snapshots at the 
EODatabaseConiexi level. This is a massive snapshot 
dumping operation in a traditional session-based editing 
context application and should be used very sparingly. 

Things to Look for 

If you have an object model where important entities 
have many relationships hanging off of them, you will 
want to look for opportunities to create a batch fault and 
optimize the performance of your application. If you have 
an array of objects that also have important individual to- 
one relationship targets, think seriously about creating a 
batch fault for those as well. 

Faulting is a very cooi mechanism that significantly 
simplifies the problem of whether or not to fetch the 
entire object graph based upon an entity. If you don’t 
need to fault an EO into memory, then it is best to leave 
it alone; however, if you do need an EO on the other side 
of a relationship, then just reach out and fault it. El 
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by Jeff elites <online@mactech .com> 


In our previous column we began coverage of a set of 
Cedinologies that fm calling the "New Basics," in recognition tliat 
'^the things iliat e\ery programmer should know" are changing, and 
as they change we're conveiging on a set which is die same for all 
programmers—there are no longer different sets for different 
platforms. This is in part because the ftindamentiil, low-level 
differences betw^een operating systems are shrinking, and in pan 
becaiLse the focus is shifting toward technologies which are new to 
all platforms, and which are being embraced by all platforms as they 
emerge. We also noted that this is leading to a sort of imprompai 
cooperation, and companies like fBM which used to be archetypal 
bad guy are now great sources of infonnation for Macintosh 
programmers who are new to the Unix side of computing, Oiir first 
New Basic was XML, wliich is the mast-hyped technology^ of the 
day, and is likely to dotninate infonnation interchange for some time 
to Tliis month we are going to Ctke a look at threading—both 
how it will be conceptually different under Mac OS X than under 
Mac OS 9, and how it will l^e more important tliere as well 

Preemptive Threading 

Most Macintosh developers will be accustomed to a 
“eex^perative'' environment, where an application lias exclusive use 
of the processor (and otlier system re.sources) until it explicitly yields 
control to other waiting processes. Threading under Mac OS 9 is also 
typically cooperatively sc'heduled, so that threads within a single 
application have to explicitly yield for otlier threads to proceed. Tliis 
type of .scheduling simplifies certain Ksues surrounding concurrent 
access to memory and sysi^m resources, but it can be difficailt for a 
developer to know how often, and wlien, to yield tlie processor in 
order to provide the test overall sy^stem performance. Also, the 
majority of the Too]lx)x is not thread safe, so that you have to be 
very careful atein the types of operations you perform outside of 
the main tliread. As a result, under Mac OS 9 applic-ations tend to be 
single-threaded if at all possible. 

Under Mac OS X, as under otlier Unix-based operating systems, 
both processes and tiireads are scheduled preemptively, so that the 
kernel makes all scheduling decisions and a tliread or process can 
be interrupted at any time. From tlie point of view of a programmer, 
this means that you can never be sure that tw^o operations witiiin 
your application will take place without another process 
interrupting. The benefit of this approach is tliat you never lias to 
explicitly code time-consuming sections of your application to yield 
tlie processor in order to prevent freezing the usef s system for long 
periods, :;tnd you can perform bkx'king I/O operations in a thread 
and know tliat oftier tlireads and processes will happily proceed 
wMe yours Is waiting for data to be read traasfeired. This simplifies 
miiny uses of threads, but introduces complicati{)ns of its own: you 


have to guard critical sections of code and data from concurrent 
access if tliey are going to be used by multiple tlireads (even reading 
data from a variable cannot be assumed to be an atomic operation), 
and you can’t assume that the state of the system lias not changed 
from one line of code to tlie next (for instance, it isn't reliable to 
check for tlie existence of a file and then try' to open it as a separate 
step, because tlie file could be deleted in betw^een the two 
operations, even if they occur back-to-back within your program). 
Prc’cmpiive scheduling requires a certain paranoia on the part of the 
pn3grammer, but it leads to an overall more responsive and relial^le 
system, and it allow's simple applications to be written simply, 
without worrying tliat tliey might accidentally liijack the processor 
And of counse, threading makes it ptxssible for a single application to 
take acK^antage of multiple processors on systems which have them, 
and in fact on such 5y.stem5 two direads wdtliin a single application 
cm be executing at literally the same time, 

POSK Threads 

The fundamental tlircading library' under Mac OS X is POSIX 
Threads, or Pilireads for short. This w'iU te new to veteran OpenStep 
programmers as well as to ckssic Miicintosh programmers, as Mac 
OS X Server and previous NeXT-derived Of^erating sy'stems used a 
different tlireading library’, called Ctlireads. The big benefit of 
IThreads is tliat applications using them should be portable to other 
POSIX-compliant operating .systems (if tlie rest of the code Is 
portable, of course), and tills w'ill make it tliat much easier to bring 
standard Unix tcx>ls and applications over to tlie Macintosh. For most 
applications it won't te nec'essary to use tlie PtJireads library directly, 
as Cocoa has its own threading facilities which provide a higher-level 
view and insulate the programmer from tlie details of the underlying 
threading library. Even so, the concepaial model remains the same, 
and Macinto.sh programmers which are new to preemptive threading 
will benefit from tlie wealth of itifbrmation there Is available on 
POSIX threading. Also, if you pirn to develop (or port) more 
tniditional Llnix-style applications you will need to know about the 
lower-le\^el libraries in more detail 

A good starting point is the article Hmv to program iiitb threads 
on SunWorld Online, which talks aliout progr^immiog with threads 
in general and the advantages that they offer. Next, IBM’s 
developerWorks site has a series of articles w'hich cover POSIX 
tlireads specifically Like many of their articles, these are written with 
a Linux audience in mind, but most of the information is nevertheless 
relevant, as POSIX is explicitly ctoss platfonn, These articles will give 
you a good feel for the issues involved, and point out the potential 
complexities of using threads. 

How to program with threads (SunWorld Online) 

<http://www.sunworld.conn/swol-02-1996/swol-02-threadshtml> 
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POSIX threads explained, Part 1: A simple and nimble tool for 
memory sharing 

<http://www4Jbmxom/software/developer/library/posix1.ht^^^ 

POSIX threads explained, Part 2: The little things called mutexes 
<http://vwvw-4.ibm,com/software/developer/library/posix2/index,html> 

POSIX threads explained, Part 3: improve effidency with condition variables 
<http://www-4.ibnn,com/software/developer/library/l-posix3/index.html> 

After you Ve gotten a handle on the major concepts, you'll want 
to find more in-depth coverage of the details of using Pthreads. 
There are several online mtorials which can help. In particular, 
Getting Started With POSIX Threads is a brief tutorial which will help 
solidify some key points, and then you can move on to more 
comprehensive coverage in Mulii-Tbreaded Programming With 
POSIX Threads md POSIX ^Ihreads Progmmming, both of which are 
quite thorough. 
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Getting Started With POSIX Threads 
<http://nna5.G.unnass.edu/~wagner/threads_^html/tutorial.html> 

Multi-Threaded Programming With POSIX Threads 

<http://users.actcom.coJI/-'Choo/lupg/tutorials/multi-thread/ 

multi-thread.html> 

POSIX Threads Programming 

<http://wwwJlnLgov/computing/tutoriais/workshops/workshop/ 

pthreads/MAIN.htmI> 

If you are curious about other issues surrounding direading, 
you should check the comp.programming.threads FAQ. .Also, if you 
are interested in the different possible strategies for actually 
implement a threading library, the Navy has an article which covers 
the strengths and weaknesses of three different approaches. Finally, 
you may want to visit die Programming POSIX Threads web site, 
which has pointers to further information. 

comp-pmgramming.threads FAQ 
<http://www.serpentinexom/«bos/threads-faq> 

Three POSIX Threads' Implementations 
<http://www.nswc,navy mil/cosip/feb99/cots0299-1 .shtml> 

Programming POSIX Threads 
<http://www.humanfaaor.com/pthreads/> 

There are several books about Pthreads, and 1 always find it 
helpful to have a detailed printed reference to augment all of the 
web-based information. Programming udth POSIX Threadsby David 
R. Butenhof (ISBN: 0201-63392-2) is my favorite and is often 
recommended by others, but there are several alternatives available, 
including Pthreads Programming (ISBN: 1-56592-115-1) and 
Multithreaded Programming With Pthreads GSBN: 0136807291). 
Take a look and see which one suites you the best. 

Now you should be up to speed on basic number two. Keep 
your eye on this column in coming months, because we’re not done 
with the New Basics yet! B 
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• Unique command'builders help you learn to 
assemble commands 
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Linux gives you all the 
— without the pricetag. 
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1000 applications on 5 CDs 
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A POWERFUL development 
environment: C/C++, Fortran, 
Pascal, Java, Perl, Python... 

A POWERFUL server platform: 
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